View 1990799_249645.PDF datasheet online --- IC-ON-LINE

Datasheet File OCR Text:

PRELIMINARY DRIVER MANUAL PMC-990799 ISSUE 1
PM7350 S/UNI-DUPLEX DRIVER
S/UNI-DUPLEX DRIVER MANUAL
PM7350
S/UNI-
TM
DUPLEX
S/UNI-DUPLEX
DUAL SERIAL LINK, PHY MULTIPLEXER
DRIVER MANUAL
PRELIMINARY ISSUE 1: JULY 1999
PROPRIETARY AND CONFIDENTIAL TO PMC-SIERRA, INC., AND FOR ITS CUSTOMERS' INTERNAL USE
PRELIMINARY DRIVER MANUAL PMC-990799 ISSUE 1
PM7350 S/UNI-DUPLEX DRIVER
S/UNI-DUPLEX DRIVER MANUAL
PROPRIETARY AND CONFIDENTIAL TO PMC-SIERRA, INC., AND FOR ITS CUSTOMERS' INTERNAL USE
PRELIMINARY DRIVER MANUAL PMC-990799 ISSUE 1
PM7350 S/UNI-DUPLEX DRIVER
S/UNI-DUPLEX DRIVER MANUAL
REVISION HISTORY Issue No. Issue 1 Issue Date July 1999 Originator James Lamothe Details of Change Document created from S/UNI-DUPLEX Driver Design Spec (PMC-981033 Issue 2) and the S/UNI-VORTEX Driver Manual (PMC-990786 Issue 1)
PROPRIETARY AND CONFIDENTIAL TO PMC-SIERRA, INC., AND FOR ITS CUSTOMERS' INTERNAL USE
3
PRELIMINARY DRIVER MANUAL PMC-990799 ISSUE 1
PM7350 S/UNI-DUPLEX DRIVER
S/UNI-DUPLEX DRIVER MANUAL
ABOUT THIS MANUAL This manual describes the S/UNI-DUPLEX device driver. It describes the driver's functions, data structures, and architecture. This manual focuses on the driver's interfaces to your application, real-time operating system, and to the S/UNI-DUPLEX device. It also describes in general terms how to modify and port the driver to your software and hardware platform. Audience This manual was written for people who need to: * * * Evaluate and test the S/UNI-DUPLEX device Modify and add to the S/UNI-DUPLEX driver's functions Port the S/UNI-DUPLEX driver to a particular platform.
References For more information about the S/UNI-DUPLEX driver, see the driver's release notes. For more information about the S/UNI-DUPLEX device, see the following documents: * * * S/UNI-DUPLEX (Dual Serial Link, Phy Multiplexer) Datasheet: PMC-980581 S/UNI-DUPLEX (Dual Serial Link, Phy Multiplexer) Short Form Datasheet: PMC-990174) S/UNI-DUPLEX and S/UNI-VORTEX Technical Overview: PMC-981025
Note: Ensure that you use the document that PMC_Sierra issued for your version of the device and driver.
PROPRIETARY AND CONFIDENTIAL TO PMC-SIERRA, INC., AND FOR ITS CUSTOMERS' INTERNAL USE
4
PRELIMINARY DRIVER MANUAL PMC-990799 ISSUE 1
PM7350 S/UNI-DUPLEX DRIVER
S/UNI-DUPLEX DRIVER MANUAL
TABLE OF CONTENTS
1 2 Driver Porting Quick Start....................................................................................................................13 Driver Functions and Features ............................................................................................................15 2.1 Driver Architecture .....................................................................................................................16 2.1.1 Driver API Module ........................................................................................................17 2.1.2 Driver Real-Time-OS Interface Module ........................................................................18 2.1.3 Driver Hardware-Interface Module ...............................................................................18 2.1.4 Driver Library Module ...................................................................................................18 2.1.5 Device Data-Block Module ...........................................................................................18 2.1.6 Interrupt-Service Routine Module ................................................................................19 2.1.7 Deferred-Processing Routine Module ..........................................................................19 Driver Software States...............................................................................................................19 Processing Flows.......................................................................................................................20 2.3.1 Device Initialization, Re-initialization, and Shutdown ...................................................21 2.3.2 Cell Extraction ..............................................................................................................22 2.3.3 Interrupt Servicing ........................................................................................................23 2.3.4 Polling Servicing ...........................................................................................................26
2.2 2.3
3
Driver Data Structures.........................................................................................................................29 3.1 Cell Data Structures ..................................................................................................................29 3.1.1 Cell-Header Data Structure ..........................................................................................29 3.1.2 Cell-Control Data Structure ..........................................................................................29 Device-Configuration Data Structures .......................................................................................30 3.2.1 Initialization Data Structure ..........................................................................................30 3.2.2 Register Data Structure................................................................................................31 Device-Context Data Structures ................................................................................................33 3.3.1 Global Driver-Database Structure ................................................................................33 3.3.2 Device Data-Block Structure ........................................................................................34 Interrupt Data Structures ...........................................................................................................36 3.4.1 Interrupt-Enable Data Structure ...................................................................................36 3.4.2 Interrupt-Context Data Structure ..................................................................................37 Count Structures........................................................................................................................38 3.5.1 HSS Counts..................................................................................................................38 3.5.2 Statistical Counts..........................................................................................................38
3.2
3.3
3.4
3.5
4
Application Interface Functions ...........................................................................................................43 4.1 Driver Initialization and Shutdown .............................................................................................44 4.1.1 duplexModuleInit: Initializing Driver Modules ...............................................................44 4.1.2 duplexModuleShutdown: Shutting Down Driver Modules.............................................45
PROPRIETARY AND CONFIDENTIAL TO PMC-SIERRA, INC., AND FOR ITS CUSTOMERS' INTERNAL USE
5
PRELIMINARY DRIVER MANUAL PMC-990799 ISSUE 1
PM7350 S/UNI-DUPLEX DRIVER
S/UNI-DUPLEX DRIVER MANUAL
4.2
Device Addition, Reset, and Deletion ........................................................................................45 4.2.1 duplexAdd: Adding Devices..........................................................................................45 4.2.2 duplexReset: Resetting Devices...................................................................................46 4.2.3 duplexRemoteReset: Resetting Other Devices ............................................................47 4.2.4 duplexDelete: Deleting Devices....................................................................................47 Reading from and Writing to Devices ........................................................................................48 4.3.1 duplexRead: Reading from Device Registers...............................................................48 4.3.2 duplexWrite: Writing to Device Registers .....................................................................49 Device Initialization ....................................................................................................................49 4.4.1 duplexInit: Initializing Devices.......................................................................................49 4.4.2 duplexInstallIndFn: Installing Indication Callback Functions ........................................50 4.4.3 duplexRemoveIndFn: Removing Indication Callback Functions ..................................51 Device Activation and Deactivation ...........................................................................................52 4.5.1 duplexActivate: Activating Devices ...............................................................................52 4.5.2 duplexDeactivate: Deactivating Devices.......................................................................52 Device Diagnostics ....................................................................................................................53 4.6.1 duplexRegisterTest: Verifying Device Register Access.................................................53 4.6.2 duplexLoopback: Enabling/Disabling Diagnostic or Line Loopback .............................54 4.6.3 duplexGetClockStatus: Monitoring Device Clocks .......................................................55 HSS Link Configuration .............................................................................................................56 4.7.1 duplexHssActiveLnkGetCfg: Getting HSS-Link Selection Method Information ............56 4.7.2 duplexHssActiveLnkSetCfg: Setting Active HSS Links ................................................57 4.7.3 duplexHssGetConfig: Getting HSS-Link Configuration Information .............................57 4.7.4 duplexHssSetConfig: Modifying HSS-Link Configuration Information..........................58 4.7.4 58 HSS-Link Cell Insertion and Extraction .....................................................................................59 4.8.1 duplexInsertCell: Inserting Cells into HSS Links ..........................................................60 4.8.2 duplexExtractCell: Extracting Cells from HSS Links.....................................................61 4.8.3 duplexCheckExtractFifos: Getting Contents of the Extract-FIFO-Ready Register .......63 4.8.4 duplexEnableRxCellInd: Enabling the Received Cell Indicator ....................................64 4.8.5 duplexInstallCellTypeFn: Installing Callback Functions ................................................64 BOC Transmission and Reception.............................................................................................65 4.9.1 duplexTxBOC: Transmitting BOC .................................................................................65 4.9.2 duplexRxBOC: Reading from Received BOC ..............................................................66 4.9.3 duplexSetAutoRDITx: Transmitting Remote-Defect Indication Code Words.................67 4.9.4 duplexSciAnyPhyGetConfig: Getting SCI-PHY/Any-PHY Configuration Information...68 4.9.5 duplexSciAnyPhySetConfig: Configuring HSS-Links ...................................................70
4.3
4.4
4.5
4.6
4.7
4.8
4.9
4.10 Clocked Serial-Data Interface Functions ...................................................................................71 4.10.1 duplexRxSerChnlReadReg: Reading from Receive Serial-Channel Context Bytes ....71 4.10.2 duplexRxSerChnlWriteReg: Writing to Receive Serial-Channel Context Bytes ...........72 4.10.3 duplexRxSerChnlHCSCntResetEn: Enabling Auto Reset of HCS Error Registers......73 4.10.4 duplexTxSerChnlReadReg: Reading from Transmit Serial-Channel Context Bytes ....74 4.10.5 duplexTxSerChnlWriteReg: Writing to Transmit Serial-Channel Context Bytes ...........75
PROPRIETARY AND CONFIDENTIAL TO PMC-SIERRA, INC., AND FOR ITS CUSTOMERS' INTERNAL USE
6
PRELIMINARY DRIVER MANUAL PMC-990799 ISSUE 1
PM7350 S/UNI-DUPLEX DRIVER
S/UNI-DUPLEX DRIVER MANUAL
4.11 Statistics Collection ...................................................................................................................76 4.11.1 duplexGetHssLnkRxCounts: Accumulating Counts for Received Cells .......................76 4.11.2 duplexGetHssLnkTxCounts: Accumulating Counts for Transmitted Cells ....................77 4.11.3 duplexGetAllHssCounts: Accumulating Counts for All Cells ........................................78 4.11.4 duplexGetStatisticCounts: Retrieving Driver Statistical Counts ...................................79 4.11.5 duplexResetStatisticCounts: Resetting Driver Statistical Counts.................................79 4.12 Indication Callbacks...................................................................................................................80 4.12.1 indDuplexNotify: Notifying the Application of Significant Events ..................................80 4.12.2 indDuplexRxBOC: Notifying the Application of Received BOC....................................80 4.12.3 indDuplexRxCell: Notifying the Application of Ready Extract-Cell-FIFOs ....................81 5 Real-Time-OS Interface Functions......................................................................................................83 5.1 Memory Allocation and Deallocation .........................................................................................84 5.1.1 sysDuplexMemAlloc: Allocating Memory .....................................................................84 5.1.2 sysDuplexMemFree: Deallocating Memory..................................................................85 Buffer Management ...................................................................................................................85 5.2.1 duplexGetIndBuf: Getting DPR Buffers ........................................................................85 5.2.2 duplexReturnIndBuf: Returning DPR Buffers ...............................................................86 Timer Operations .......................................................................................................................86 5.3.1 sysDuplexDelayFn: Delaying Functions .......................................................................86 Semaphore Operations .............................................................................................................86 5.4.1 sysDuplexSemCreate: Creating Semaphores..............................................................87 5.4.2 sysDuplexSemDelete: Deleting Semaphores...............................................................87 5.4.3 sysDuplexSemTake: Taking Semaphores.....................................................................87 5.4.4 sysDuplexSemGive: Giving Semaphores.....................................................................87
5.2
5.3
5.4
6
Hardware Interface Functions .............................................................................................................89 6.1 Device Register Access.............................................................................................................89 6.1.1 sysDuplexRawRead: Reading from Register Address Locations ................................90 6.1.2 sysDuplexRawWrite: Writing to Register Address Locations .......................................90 6.1.3 sysDuplexDeviceDetect: Getting Device Base Addresses...........................................90 Interrupt Servicing .....................................................................................................................91 6.2.1 duplexISR: Registering Interrupt Statuses ...................................................................92 6.2.2 duplexDPR: Processing Interrupts ...............................................................................92 6.2.3 sysDuplexIntInstallHandler: Installing Interrupt Service Functions ..............................93 6.2.4 sysDuplexIntRemoveHandler: Removing Interrupt Service Functions ........................94 6.2.5 sysDuplexIntHandler: Calling duplexISR......................................................................94 6.2.6 sysDuplexDPRTask: Calling duplexDPR ......................................................................95
6.2
7
Porting Drivers.....................................................................................................................................97 7.1 7.2 Driver Source Files ....................................................................................................................97 Driver Porting Procedures .........................................................................................................97 7.2.1 Porting Driver OS Extensions.......................................................................................98
PROPRIETARY AND CONFIDENTIAL TO PMC-SIERRA, INC., AND FOR ITS CUSTOMERS' INTERNAL USE
7
PRELIMINARY DRIVER MANUAL PMC-990799 ISSUE 1
PM7350 S/UNI-DUPLEX DRIVER
S/UNI-DUPLEX DRIVER MANUAL
7.2.2 7.2.3 7.2.4
Porting Drivers to Hardware Platforms.......................................................................100 Porting Driver Application-Specific Elements .............................................................102 Building Drivers ..........................................................................................................103
Appendix: Coding Conventions................................................................................................................105 Acronyms .................................................................................................................................................109 Index ........................................................................................................................................................111 Contacting PMC-Sierra, Inc. ....................................................................................................................118
PROPRIETARY AND CONFIDENTIAL TO PMC-SIERRA, INC., AND FOR ITS CUSTOMERS' INTERNAL USE
8
PRELIMINARY DRIVER MANUAL PMC-990799 ISSUE 1
PM7350 S/UNI-DUPLEX DRIVER
S/UNI-DUPLEX DRIVER MANUAL
LIST OF FIGURES
Figure 1: Driver Architecture ......................................................................................................................17 Figure 2: Driver Software States ................................................................................................................20 Figure 3: Device Initialization, Re-initialization, and Shutdown .................................................................22 Figure 4: Cell Extraction.............................................................................................................................23 Figure 5: Interrupt Service Model ..............................................................................................................24 Figure 6: Polling Service Model .................................................................................................................26 Figure 7: Application Interface ...................................................................................................................44 Figure 8: Real-Time OS Interface ..............................................................................................................84 Figure 9: Hardware Interface .....................................................................................................................89 Figure 10: Driver Source Files ...................................................................................................................97
PROPRIETARY AND CONFIDENTIAL TO PMC-SIERRA, INC., AND FOR ITS CUSTOMERS' INTERNAL USE
9
PRELIMINARY DRIVER MANUAL PMC-990799 ISSUE 1
PM7350 S/UNI-DUPLEX DRIVER
S/UNI-DUPLEX DRIVER MANUAL
PROPRIETARY AND CONFIDENTIAL TO PMC-SIERRA, INC., AND FOR ITS CUSTOMERS' INTERNAL USE
10
PRELIMINARY DRIVER MANUAL PMC-990799 ISSUE 1
PM7350 S/UNI-DUPLEX DRIVER
S/UNI-DUPLEX DRIVER MANUAL
LIST OF TABLES
Table 1: Driver Functions and Features .....................................................................................................15 Table 2: Driver Software States..................................................................................................................20 Table 3: Cell Header Structure: sDPX_CELL_HDR ...................................................................................29 Table 4: Cell Control Structure: sDPX_CELL_CTRL..................................................................................30 Table 5: Initialization Vector: sDPX_INIT_VECTOR ...................................................................................31 Table 6: Device Registers: sDPX_REGS ...................................................................................................31 Table 7: SCI-PHY/Any-PHY Registers: sDPX_SCI_ANY_PHY_REGS.....................................................32 Table 8: HSS Link Registers: sDPX_HSS_REGS......................................................................................32 Table 9: Clocked Serial-Interface Registers: sDPX_CLK_SER_REGS .....................................................33 Table 10: Global Driver Database: sDPX_GDD .........................................................................................34 Table 11: Device Data Block: sDPX_DDB..................................................................................................34 Table 12: Interrupt Enables: sDPX_INT_ENBLS .......................................................................................37 Table 13: Interrupt Context: sDPX_INT_CTXT...........................................................................................38 Table 14: HSS Counts: sDPX_HSS_CNTS................................................................................................38 Table 15: Statistical Counts: sDPX_STAT_COUNTS .................................................................................39 Table 16: Definition of Variable Types.......................................................................................................105 Table 17: Variable Naming Conventions...................................................................................................106 Table 18: Function and Macro Naming Conventions ...............................................................................107
PROPRIETARY AND CONFIDENTIAL TO PMC-SIERRA, INC., AND FOR ITS CUSTOMERS' INTERNAL USE
11
PRELIMINARY DRIVER MANUAL PMC-990799 ISSUE 1
PM7350 S/UNI-DUPLEX DRIVER
S/UNI-DUPLEX DRIVER MANUAL
PROPRIETARY AND CONFIDENTIAL TO PMC-SIERRA, INC., AND FOR ITS CUSTOMERS' INTERNAL USE
12
PRELIMINARY DRIVER MANUAL PMC-990799 ISSUE 1
PM7350 S/UNI-DUPLEX DRIVER
S/UNI-DUPLEX DRIVER MANUAL
1
DRIVER PORTING QUICK START This section summarizes how to port the S/UNI-DUPLEX device driver to your hardware and operating system (OS) platform. Note: Because each platform and application is unique, this manual can only offer guidelines for porting the S/UNI-DUPLEX driver. The code for the S/UNI-DUPLEX driver is organized into C source files. You may need to modify the code or develop additional code. The code is in the form of constants, macros, and functions. For the ease of porting, the code is grouped into source files (src) and include files (inc). The src files contain the functions and the inc files contain the constants and macros. To port the S/UNI-DUPLEX driver to your platform: 1. Port the driver's OS extensions (page 98): * * * Data types OS-specific services Utilities and interrupt services that use OS-specific services
2. Port the driver to your hardware platform (page 100): * * * Port the device detection function. Port low-level device read-and-write macros. Define hardware system-configuration constants.
3. Port the driver's application-specific elements (page 102): * * Define the task-related constants. Code the callback functions.
4. Build the driver (page 103). For more information about porting the S/UNI-DUPLEX driver, see section 7.
PROPRIETARY AND CONFIDENTIAL TO PMC-SIERRA, INC., AND FOR ITS CUSTOMERS' INTERNAL USE
13
PRELIMINARY DRIVER MANUAL PMC-990799 ISSUE 1
PM7350 S/UNI-DUPLEX DRIVER
S/UNI-DUPLEX DRIVER MANUAL
PROPRIETARY AND CONFIDENTIAL TO PMC-SIERRA, INC., AND FOR ITS CUSTOMERS' INTERNAL USE
14
PRELIMINARY DRIVER MANUAL PMC-990799 ISSUE 1
PM7350 S/UNI-DUPLEX DRIVER
S/UNI-DUPLEX DRIVER MANUAL
2
DRIVER FUNCTIONS AND FEATURES The following table lists the main functions and features offered by the S/UNI-DUPLEX driver. You can alter these functions by modifying or adding to the driver's code. Table 1: Driver Functions and Features Functions Device Addition and Deletion (page 45) Description These functions perform the following tasks: * * * Device Initialization (page 49) Device Diagnostics (page 53) These functions write values to registers and read them back to verify the microprocessor's input and output interface with the device. They enable and disable internal and external loopback for the S/UNI-DUPLEX device's high-speed serial (HSS) interfaces. They also monitor the device's clocks. These functions configure the HSS links of the S/UNI-DUPLEX device by programming the HSS link registers according to the parameters specified. These functions insert cells into, and extract cells from, the S/UNI-DUPLEX device control channels by manipulating the insert and extract FIFO control and status registers. These functions transmit and receive BOC on the HSS interfaces. Writing to the transmit-BOC registers transmits BOC. BOC is received by monitoring the receive-BOC status-registers. Reset new devices Allocate and initialize memory that will store context information for new devices Deallocate device context memory during device shutdown
These functions initialize the S/UNI-DUPLEX device and its associated context structures.
HSS Link Configuration (page 56) Cell Insertion and Extraction (page 59) BOC Transmission and Reception (page 65)
PROPRIETARY AND CONFIDENTIAL TO PMC-SIERRA, INC., AND FOR ITS CUSTOMERS' INTERNAL USE
15
PRELIMINARY DRIVER MANUAL PMC-990799 ISSUE 1
PM7350 S/UNI-DUPLEX DRIVER
S/UNI-DUPLEX DRIVER MANUAL
Statistics Collection (page 67) Interrupt Servicing (page 23)
These functions retrieve the device counts (including cells received, cells transmitted, and errored cells received) for accumulation by the application. These functions clear the interrupts raised by the S/UNI-DUPLEX device. Then they queue the interrupt status for later processing by a deferred interrupt-processing routine (DPR). The DPR runs in the context of a separate task within the RTOS and takes appropriate actions based on the interrupt status queued for it by the Interrupt Servicing Routine (ISR). In polling mode, the DPR process periodically services the interrupt status.
Indication Callbacks (page 80)
The DPR uses indication callback functions to notify the application of events in the S/UNI-DUPLEX device and driver. These events include the reception of cells in the microprocessor extract cell FIFOs and the reception of valid BOC.
2.1
Driver Architecture The driver includes seven main modules: * * * * * * * Driver API module Real-time-OS interface module Hardware interface module Driver library module Device data-block module Interrupt-service routine module Deferred-processing routine module
For more information about these modules, see the following sections. Figure 1 illustrates the architectural modules of the S/UNI-DUPLEX driver.
PROPRIETARY AND CONFIDENTIAL TO PMC-SIERRA, INC., AND FOR ITS CUSTOMERS' INTERNAL USE
16
PRELIMINARY DRIVER MANUAL PMC-990799 ISSUE 1
PM7350 S/UNI-DUPLEX DRIVER
S/UNI-DUPLEX DRIVER MANUAL
Figure 1: Driver Architecture
Application Function Calls Indication Callbacks Driver API
RTOS Interface
Service Calls
Interrupt Context
Device Data Block
Interrupt Servicing Routine Hardware Interface Hardware Interrupts S/UNI-DUPLEX Device S/UNIDUPLEX Driver Register Access
2.1.1 Driver API Module The driver's API is a collection of high level functions that can be called by application programmers to configure, control, and monitor the S/UNI-DUPLEX device, such as: * * * * Initializing the device Validating device configuration Retrieving device status and statistics information. Diagnosing the device
The driver API functions use the driver library functions as building blocks to provide this system level functionality to the application programmer (see below).
RTOS
Deferred Processing Routine
Driver Library Functions
PROPRIETARY AND CONFIDENTIAL TO PMC-SIERRA, INC., AND FOR ITS CUSTOMERS' INTERNAL USE
17
PRELIMINARY DRIVER MANUAL PMC-990799 ISSUE 1
PM7350 S/UNI-DUPLEX DRIVER
S/UNI-DUPLEX DRIVER MANUAL
The driver API also consists of callback functions that notify the application of significant events that take place within the device and driver, including cell and BOC reception. 2.1.2 Driver Real-Time-OS Interface Module The driver's RTOS interface module provides functions that let the driver use RTOS services. The S/UNI-DUPLEX driver requires the memory, interrupt, and preemption services from the RTOS. The RTOS interface functions perform the following tasks for the S/UNI-DUPLEX device and driver: * * * * Allocate and deallocate memory Manage buffers for the DPR Pause task execution Manage semaphores
The RTOS interface also includes service callbacks. These are functions installed by the driver using RTOS service calls, such as install interrupts and start timers. These service callbacks are invoked when an interrupt occurs or a timer expires. Note: You must modify RTOS interface code to suit your RTOS. 2.1.3 Driver Hardware-Interface Module The S/UNI-DUPLEX hardware interface provides functions that read from and write to S/UNI-DUPLEX device-registers. The hardware interface also provides a template for an ISR that the driver calls when the device raises a hardware interrupt. You must modify this function based on the interrupt configuration of your system. 2.1.4 Driver Library Module The driver library module is a collection of low-level utility functions that manipulate the device registers and the contents of the driver's DDB. The driver library functions serve as building blocks for higher level functions that constitute the driver API module. Application software does not normally call the driver library functions. 2.1.5 Device Data-Block Module The DDB stores context information about the S/UNI-DUPLEX device, such as:
PROPRIETARY AND CONFIDENTIAL TO PMC-SIERRA, INC., AND FOR ITS CUSTOMERS' INTERNAL USE
18
PRELIMINARY DRIVER MANUAL PMC-990799 ISSUE 1
PM7350 S/UNI-DUPLEX DRIVER
S/UNI-DUPLEX DRIVER MANUAL
* * * * *
Device state Control information Initialization vector Callback function pointers Statistical counts
The driver allocates context memory for the DDB when the driver registers a new device. 2.1.6 Interrupt-Service Routine Module The S/UNI-DUPLEX driver provides an ISR called duplexISR that checks if there are any valid interrupt conditions present for the device. This function can be used by a system-specific interrupt-handler function to service interrupts raised by the device. The low-level interrupt-handler function that traps the hardware interrupt and calls duplexISR is system and RTOS dependent. Therefore, it is outside the scope of the driver. An example implementation of such an interrupt handler (see page 94) as well as installation and removal functions (see page 93 and page 94) is provided as a reference. You can customize these example implementations to suit your specific needs. See page 23 for a detailed explanation of the ISR and interrupt-servicing model. 2.1.7 Deferred-Processing Routine Module The DPR provided by the S/UNI-DUPLEX driver (duplexDPR) clears and processes interrupt conditions for the device. Typically, a system specific function, which runs as a separate task within the RTOS, executes the DPR. See page 23 for a detailed explanation of the DPR and interrupt-servicing model. 2.2 Driver Software States Figure 2 shows the software state diagram for the S/UNI-DUPLEX driver. State transitions occur on the successful execution of the corresponding transition functions shown. State information helps maintain the integrity of the driver's DDB by controlling the set of device operations allowed in each state. Table 2 describes the software states for the S/UNI-DUPLEX device as maintained by the driver.
PROPRIETARY AND CONFIDENTIAL TO PMC-SIERRA, INC., AND FOR ITS CUSTOMERS' INTERNAL USE
19
PRELIMINARY DRIVER MANUAL PMC-990799 ISSUE 1
PM7350 S/UNI-DUPLEX DRIVER
S/UNI-DUPLEX DRIVER MANUAL
Figure 2: Driver Software States
Empty
duplexAdd duplexDelete
Present duplexInit duplexReset duplexActivate Init duplexDeactivate
duplexReset
duplexReset
Active
Table 2: Driver Software States State Empty Present Description The S/UNI-DUPLEX device is not registered. This is the initial state. The driver has detected the S/UNI-DUPLEX device and the drive has passed power-on self-tests. The driver has allocated memory to store context information about this device. An initialization vector passed by the application has successfully initialized the S/UNI-DUPLEX device. The initialization parameters have been validated and the device has been configured by writing appropriate bits in the control registers of the device. The S/UNI-DUPLEX device has been activated. This means that the device interrupts have been enabled and the device is ready for normal operation.
Init
Active
2.3
Processing Flows This section describes some of the main processing flows of the S/UNI-DUPLEX driver: * Device initialization, re-initialization, and shutdown
PROPRIETARY AND CONFIDENTIAL TO PMC-SIERRA, INC., AND FOR ITS CUSTOMERS' INTERNAL USE
20
PRELIMINARY DRIVER MANUAL PMC-990799 ISSUE 1
PM7350 S/UNI-DUPLEX DRIVER
S/UNI-DUPLEX DRIVER MANUAL
* * *
Cell extraction Interrupt servicing Polling servicing
The flow diagrams presented here illustrate the sequence of operations that take place for different driver functions. The diagrams also serve as a guide to the application programmer by illustrating the sequence in which the application must invoke the driver API. 2.3.1 Device Initialization, Re-initialization, and Shutdown The following figure shows the functions and process that the driver uses to initialize, re-initialize, and shutdown the S/UNI-DUPLEX device.
PROPRIETARY AND CONFIDENTIAL TO PMC-SIERRA, INC., AND FOR ITS CUSTOMERS' INTERNAL USE
21
PRELIMINARY DRIVER MANUAL PMC-990799 ISSUE 1
PM7350 S/UNI-DUPLEX DRIVER
S/UNI-DUPLEX DRIVER MANUAL
Figure 3: Device Initialization, Re-initialization, and Shutdown
START
duplexAdd
Detects the device being added in the hardware (using sysDuplexDeviceDetect), allocates memory for storing device context information, and applies a software reset to the device. Initializes the device based on an initialization vector provided by the application. The initialization vector is validated by the application and stored by the driver as part of device context information. The device registers are then configured accordingly. (OPTIONAL) Installs callback functions using these two functions if necessary. These callbacks can also be installed by passing them in the initialization vector argument of the duplexInit function. Prepares the device for normal operation by enabling interrupts and other global enables like HSS links transmitter. An ISR function is installed using sysDuplexIntInstallHandler. The device is now operational and all other API can be invoked. In order to re-initialize the device, resets the device using duplexReset and goes through the initialization sequence again.
duplexInit
duplexInstallIndFn duplexInstallCellTypeFn
duplexActivate
duplexReset
duplexDeactivate
De-activates the device and removes it from normal operation. This involves disabling the device interrupts. The ISR routine for this device is removed using sysDuplexIntRemoveHandler. Applies a software reset to the device to put it in its default startup state. It also resets the context information for that device.
duplexReset
duplexDelete
Removes the device from the list of devices being controlled by the S/UNI-DUPLEX driver. This function de-allocates the device context information for the device being deleted.
END
2.3.2 Cell Extraction The following figure shows the functions and process that the driver uses to extract cells from the S/UNI-DUPLEX device.
PROPRIETARY AND CONFIDENTIAL TO PMC-SIERRA, INC., AND FOR ITS CUSTOMERS' INTERNAL USE
22
PRELIMINARY DRIVER MANUAL PMC-990799 ISSUE 1
PM7350 S/UNI-DUPLEX DRIVER
S/UNI-DUPLEX DRIVER MANUAL
Figure 4: Cell Extraction
START
The deferred processing routine invokes this indication callback function to inform the application of a cell reception. The indDuplexRxCell function is typically implemented as a message queuing function that sends a message to another task (referred to henceforth as the cell reception task) that is dedicated to process received cells. The deferred processing routine also disables further RX indications. The cell reception task now checks the status of the Extract FIFOs of the S/UNI-DUPLEX device. This function determines which extract FIFOs have cells to be dequeued.
indDuplexRxCell
duplexCheckExtractFifos
duplexExtractCell
Cells are now dequeued by repeatedly invokin g duplexExtractCell till the Extract FIFOs ar e empty. The message completion is detected by an End of Messa ge bit in a cell type flag output from pCellTypeFn function. The function is installed by the application as a callback function. The Extract FIFOs are again checked to see if there are any more cells to be extracted. After extracting all the cells from the Extract FIFOs of the S/UNI-DUPLEX device, the cell reception task re-enables the RX indication for the device.
duplexEnableRxInd
END
2.3.3 Interrupt Servicing The S/UNI-DUPLEX driver services device interrupts using an interrupt service routine (ISR) that traps interrupts and a deferred interrupt-processing routine (DPR) that actually processes the interrupt conditions and clears them. This lets the ISR execute quickly and exit. Most of the time-consuming processing of the interrupt conditions is deferred to the DPR by queuing the necessary interrupt-context information to the DPR task. The DPR function runs in the context of a separate task within the RTOS. Note: Since the DPR task processes potentially serious interrupt conditions, you should set the DPR task's priority higher than the application task interacting with the S/UNI-DUPLEX driver. The driver provides system-independent functions, duplexISR and duplexDPR. You must fill in the corresponding system-specific functions, sysDuplexISR and sysDuplexDPR. The system-specific functions isolate the system-specific communication mechanism (between the ISR and DPR) from the system-independent functions, duplexISR and duplexDPR. Figure 5 illustrates the interrupt service model used in the S/UNI-DUPLEX driver design.
PROPRIETARY AND CONFIDENTIAL TO PMC-SIERRA, INC., AND FOR ITS CUSTOMERS' INTERNAL USE
23
PRELIMINARY DRIVER MANUAL PMC-990799 ISSUE 1
PM7350 S/UNI-DUPLEX DRIVER
S/UNI-DUPLEX DRIVER MANUAL
Figure 5: Interrupt Service Model
Interrupt Context Information
sysDuplexIntHandler duplexISR
sysDuplexDPRTask duplexDPR
Indication Callbacks Application
Note: Instead of using an interrupt service model, you can use a polling service model in the S/UNI-DUPLEX driver to process the device's event-indication registers (see page 26). Calling duplexISR An interrupt handler function, which is system dependent, must call duplexISR. But first, the low-level interrupt-handler function must trap the device interrupts. You must implement this function for your system. As a reference, an example implementation of the interrupt handler (sysDuplexIntHandler) appears on page 94. You can customize this example implementation to suit your needs. The interrupt handler that you implement (sysDuplexIntHandler) is installed in the interrupt vector table of the system processor. Then it is called when one or more S/UNI-DUPLEX devices interrupt the processor. The interrupt handler then calls duplexISR for each device in the active state. The duplexISR function reads from the master interrupt-status register and the miscellaneous interrupt-status register of the S/UNI-DUPLEX. Then duplexISR returns with this status information if a valid status bit is set. If a valid status bit is set, the duplexISR also disables that device's interrupts. The sysDuplexIntHandler function then sends a message to the DPR task that consists of the device handles of all the S/UNI-DUPLEX devices that had valid interrupt conditions. Note: Normally you should save the status information for deferred interrupt processing by implementing a message queue. The interrupt handler sends the status information to the queue by the sysDuplexIntHandler.
PROPRIETARY AND CONFIDENTIAL TO PMC-SIERRA, INC., AND FOR ITS CUSTOMERS' INTERNAL USE
24
PRELIMINARY DRIVER MANUAL PMC-990799 ISSUE 1
PM7350 S/UNI-DUPLEX DRIVER
S/UNI-DUPLEX DRIVER MANUAL
Calling duplexDPR The sysDuplexDPRTask function is a system specific function that runs as a separate task within the RTOS. You should set the DPR task's priority higher than the application task(s) interacting with the S/UNI-DUPLEX driver. In the message-queue implementation model, this task has an associated message queue. The task waits for messages from the ISR on this message queue. When a message arrives, sysDuplexDPRTask calls the DPR (duplexDPR). Then duplexDPR processes the status information and takes appropriate action based on the specific interrupt condition detected. The nature of this processing can differ from system to system. Therefore, duplexDPR calls different indication callbacks for different interrupt conditions. Typically, you should implement these callback functions as simple message posting functions that post messages to an application task. However, you can implement the indication callback to perform processing within the DPR task context and return without sending any messages. In this case, ensure that the indication function does not call any API functions that change the driver's state, such as duplexDelete. Also, ensure that the indication function is non-blocking because the DPR task executes while S/UNI-DUPLEX interrupts are disabled. You can customize these callbacks to suit your system. See page 80 for a description of the callback functions. Note: Since the duplexISR and duplexDPR routines themselves do not specify a communication mechanism, you have full flexibility in choosing a communication mechanism between the two. A convenient way to implement this communication mechanism is to use a message queue, which is a service that most RTOSs provide. You must implement the two system specific functions, sysDuplexIntHandler and sysDuplexDPRTask. When the driver calls sysDuplexIntInstallHandler for the first time, the driver installs sysDuplexIntHandler in the interrupt vector table of the processor. The sysDuplexDPRTask function is also spawned as a task during this first time invocation of sysDuplexIntInstallHandler. The sysDuplexIntInstallHandler function also creates the communication channel between sysDuplexIntHandler and sysDuplexDPRTask. This communication channel is most commonly a message queue associated with the sysDuplexDPRTask. Similarly, during removal of interrupts, the driver removes sysDuplexIntHandler from the microprocessor's interrupt vector table and deletes the task associated with sysDuplexDPRTask.
PROPRIETARY AND CONFIDENTIAL TO PMC-SIERRA, INC., AND FOR ITS CUSTOMERS' INTERNAL USE
25
PRELIMINARY DRIVER MANUAL PMC-990799 ISSUE 1
PM7350 S/UNI-DUPLEX DRIVER
S/UNI-DUPLEX DRIVER MANUAL
As a reference, this manual provides example implementations of the interrupt installation and removal functions. For more information about the interrupt installation function and prototype, see page 93. For more information about the interrupt removal function and prototype, see page 94. You can customize these prototypes to suit your specific needs. 2.3.4 Polling Servicing Instead of using an interrupt service model, you can use a polling service model in the S/UNI-DUPLEX driver to process the device's event-indication registers. Figure 6 illustrates the polling service model used in the S/UNI-DUPLEX driver design. Figure 6: Polling Service Model
sysDuplexDPRTask Indication Callbacks Application
duplexDPR
Task Delay
The polling service code includes some system specific code (prefixed by "sysDuplex"), which typically you must implement for your application. The polling service code also includes some system independent code (prefixed by "duplex") provided by the driver that does not change from system to system. In polling mode, sysDuplexIntHandler and duplexISR are not used. Instead, the driver spawns a sysDuplexDPRTask function as a task processor when the driver calls sysDuplexIntInstallHandler for the first time. In sysDuplexDPRTask, the driver-supplied DPR (duplexDPR) is periodically called for each device in the active state. The duplexDPR reads from the master interrupt-status and miscellaneous interrupt-status registers of the S/UNI-DUPLEX. If some valid status bits are set, it processes the status information and takes appropriate action based on the specific interrupt condition detected.
PROPRIETARY AND CONFIDENTIAL TO PMC-SIERRA, INC., AND FOR ITS CUSTOMERS' INTERNAL USE
26
PRELIMINARY DRIVER MANUAL PMC-990799 ISSUE 1
PM7350 S/UNI-DUPLEX DRIVER
S/UNI-DUPLEX DRIVER MANUAL
The nature of this processing can differ from system to system. Therefore, the DPR calls different indication callbacks for different interrupt conditions. You can customize these callbacks to fit your application's specific requirements. See page 80 for a description of these callback functions. Similarly, during removal of polling service, the driver removes the task associated with sysDuplexDPRTask if none of S/UNI-DUPLEX devices is activated.
PROPRIETARY AND CONFIDENTIAL TO PMC-SIERRA, INC., AND FOR ITS CUSTOMERS' INTERNAL USE
27
PRELIMINARY DRIVER MANUAL PMC-990799 ISSUE 1
PM7350 S/UNI-DUPLEX DRIVER
S/UNI-DUPLEX DRIVER MANUAL
PROPRIETARY AND CONFIDENTIAL TO PMC-SIERRA, INC., AND FOR ITS CUSTOMERS' INTERNAL USE
28
PRELIMINARY DRIVER MANUAL PMC-990799 ISSUE 1
PM7350 S/UNI-DUPLEX DRIVER
S/UNI-DUPLEX DRIVER MANUAL
3
DRIVER DATA STRUCTURES The S/UNI-DUPLEX driver uses several data structures. These structures help to: * * * * * Control and store cell header information Configure the S/UNI-DUPLEX device Identify the device's context Support interrupt processing Store indication callbacks
3.1
Cell Data Structures This section describes the data structures that the driver uses to help control cell insertion and extraction. These structures serve as templates for received and transmitted cells.
3.1.1 Cell-Header Data Structure The following structure stores cell header data. Table 3: Cell Header Structure: sDPX_CELL_HDR Member Name u1UsrPrpnd[2] u1Hdr[5] u1UDF Type UINT1 UINT1 UINT1 Description Two prepend bytes that you specify H1-H5 cell header bytes A field you define
3.1.2 Cell-Control Data Structure The following structure controls cell insertion and extraction operations.
PROPRIETARY AND CONFIDENTIAL TO PMC-SIERRA, INC., AND FOR ITS CUSTOMERS' INTERNAL USE
29
PRELIMINARY DRIVER MANUAL PMC-990799 ISSUE 1
PM7350 S/UNI-DUPLEX DRIVER
S/UNI-DUPLEX DRIVER MANUAL
Table 4: Cell Control Structure: sDPX_CELL_CTRL Member Name u4Crc32Prev Type UINT4 Description The CRC-32 value in the insert and extract CRC-32 accumulator registers after the previous cell was inserted or extracted. Used to preset the accumulator registers before inserting or extracting the next cell. The CRC-32 value in the insert and extract accumulator registers after the current cell was inserted or extracted. A flag used by the driver to indicate that the cell extracted is the last cell or first cell of a message, and is CRC protected or not. * Bit 0: * If 1, then CRC-32 on * If 0, then CRC-32 off Bit 1: * If 1, then first cell * If 0, then not first cell Bit 2: * If 1, then last cell * If 0, then not last cell
u4Crc32
UINT4
u1CellType
UINT1
*
*
3.2
Device-Configuration Data Structures This section describes the data structures that the driver uses to initialize and configure the S/UNI-DUPLEX device.
3.2.1 Initialization Data Structure The device initialization function initializes the S/UNI-DUPLEX device and its associated context structures. This involves reading an initialization vector. The driver validates this vector and then configures the S/UNI-DUPLEX device accordingly. The application sets the initialization vector before initializing a S/UNI-DUPLEX device. The initialization vector contains configuration parameters that the driver uses to program the S/UNI-DUPLEX device control-registers.
PROPRIETARY AND CONFIDENTIAL TO PMC-SIERRA, INC., AND FOR ITS CUSTOMERS' INTERNAL USE
30
PRELIMINARY DRIVER MANUAL PMC-990799 ISSUE 1
PM7350 S/UNI-DUPLEX DRIVER
S/UNI-DUPLEX DRIVER MANUAL
Note: The application must free the initialization vector memory. Table 5: Initialization Vector: sDPX_INIT_VECTOR Member Name sRegInfo Type sDPX_REGS Description Contains the values that the driver will write to the control registers of the S/UNI-DUPLEX device Indication callback function called by the DPR when a significant event occurs in the driver software Indication callback function called by the DPR to forward a received valid BOC to the application Indication callback function called by the DPR when the driver must read cells from the Extract FIFOs A Cell Type detector function that is used by the driver to determine if a cell extracted is the last or first of a particular message, and/or if it is CRC-32 protected Placeholder for future use
indNotify
DPX_IND_CB_FN
indRxBOC
DPX_IND_CB_FN
indRxCell
DPX_IND_CB_FN
pCellTypeFn
DPX_CELLTYPE_FN
u4Reserved
UINT4
3.2.2 Register Data Structure The register data structure contains the initial values that the driver will write to the S/UNI-DUPLEX device control-registers. Table 6: Device Registers: sDPX_REGS Member Name u1MasterCfg Type UINT1 Description Master configuration register
PROPRIETARY AND CONFIDENTIAL TO PMC-SIERRA, INC., AND FOR ITS CUSTOMERS' INTERNAL USE
31
PRELIMINARY DRIVER MANUAL PMC-990799 ISSUE 1
PM7350 S/UNI-DUPLEX DRIVER
S/UNI-DUPLEX DRIVER MANUAL
Member Name sSciAnyPhyRegs
Type sDPX_SCI_ANY_PHY_REGS
Description SCI-PHY/Any-PHY configuration registers HSS-link configuration registers Clocked-bit serial-interface configuration registers Interrupt enable registers
sHssRegs
sDPX_HSS_REGS
sClkSerRegs
sDPX_CLK_SER_REGS
sIntEnRegs
sDPX_INT_ENBLS
Table 7: SCI-PHY/Any-PHY Registers: sDPX_SCI_ANY_PHY_REGS Member Name u1ExtAddrMatch[2] Type UINT1 Description Extended address match [2 bytes (LSB, MSB)] Extended address mask [2 bytes (LSB, MSB)] Output address match register SCI-PHY/Any-PHY input configuration (2 bytes) Input cell available enable (4 bytes) SCI-PHY/Any-PHY output configuration SCI-PHY/Any-PHY output polling range
u1ExtAddrMask[2]
UINT1
u1OutAddrMatch u1SciAnyPhyInpCfg[2]
UINT1 UINT1
u1ICAEnable[4] u1SciAnyPhyOutCfg u1SciAnyPhyOutPollRng
UINT1 UINT1 UINT1
Table 8: HSS Link Registers: sDPX_HSS_REGS Member Name u1RxCfg[2] Type UINT1 Description Receive HSS configuration [2 bytes (RXD1, RXD2)]
PROPRIETARY AND CONFIDENTIAL TO PMC-SIERRA, INC., AND FOR ITS CUSTOMERS' INTERNAL USE
32
PRELIMINARY DRIVER MANUAL PMC-990799 ISSUE 1
PM7350 S/UNI-DUPLEX DRIVER
S/UNI-DUPLEX DRIVER MANUAL
Member Name u1RxCfg[2]
Type UINT1
Description Receive HSS configuration [2 bytes (RXD1, RXD2)] Receive HSS cell-filtering configuration (HCSPASS) [2 bytes (RXD1, RXD2)] Transmit HSS configuration
u1RxHcsPass[2]
UINT1
u1TxCfg
UINT1
Table 9: Clocked Serial-Interface Registers: sDPX_CLK_SER_REGS Member Name u1RxCfg[16] Type UINT1 Description Receive serial indirect-channel configuration Receive serial LCD-count threshold Transmit serial indirect-channel data register Transmit serial framing-bit threshold
u1RxLcdCntThresh[16] u1TxSerIndChnlData[16]
UINT1 UINT1
u1TxFrameBitThresh
UINT1
3.3
Device-Context Data Structures This section describes the data structures that the driver uses to store data about the S/UNI-DUPLEX device and related devices.
3.3.1 Global Driver-Database Structure The Global Driver Database (GDD) stores module level data, such as the number of devices that the driver controls and an array of pointers to the individual device context structures (DDBs).
PROPRIETARY AND CONFIDENTIAL TO PMC-SIERRA, INC., AND FOR ITS CUSTOMERS' INTERNAL USE
33
PRELIMINARY DRIVER MANUAL PMC-990799 ISSUE 1
PM7350 S/UNI-DUPLEX DRIVER
S/UNI-DUPLEX DRIVER MANUAL
Table 10: Global Driver Database: sDPX_GDD Member Name u1NumDevs pDdb[DPX_MAX_NUM_DEVS] Type UINT1 sDPX_DDB* Description Number of devices added Array of pointers to the individual DDBs Reserved for future use
u4Reserved
UINT4
3.3.2 Device Data-Block Structure The DDB contains device context data, such as: * * * * Device state Control data Initialization vector Callback function pointers
The driver allocates the DDB memory when the driver registers a new device. The memory is deallocated when an existing device is deleted. Table 11: Device Data Block: sDPX_DDB Member Name usrCtxt Type DPX_USR_CTXT Description This variable stores the device's role in the context of your system. The driver passes it as an input parameter when the driver calls an application callback. Pointer to system-specific device information. For example, in PCI bus environments, the bus, device, function numbers, IRQ assignment etc.
pSysInfo
VOID *
PROPRIETARY AND CONFIDENTIAL TO PMC-SIERRA, INC., AND FOR ITS CUSTOMERS' INTERNAL USE
34
PRELIMINARY DRIVER MANUAL PMC-990799 ISSUE 1
PM7350 S/UNI-DUPLEX DRIVER
S/UNI-DUPLEX DRIVER MANUAL
Member Name u4BaseAddr eDevMode
Type UINT4 eDPX_MODE
Description Base address of the device Device mode, which can be one of: * * * DPX_SCI_MASTER DPX_SCI_ANY_SLAVE DPX_CLK_BIT_SER
eDevState
eDPX_STATE
Device state, which can be one of the following enumerated type values: * * * * DPX_EMPTY DPX_PRESENT DPX_INIT DPX_ACTIVE
u1IntrProcEn
UINT1
1: Interrupt processing enabled 0: Interrupt processing disabled
sInitVector
sDPX_INIT_VECTOR
Device configuration information passed by the application to the driver. The driver writes the appropriate S/UNI-DUPLEX device registers based on the contents of this vector. Maintains a snapshot of the current interrupt-enables registers for the S/UNI-DUPLEX device Indication callback function called by the DPR when a significant event occurs in the driver software
sIntEnbls
sDPX_INT_ENBLS
indNotify
DPX_IND_CB_FN
PROPRIETARY AND CONFIDENTIAL TO PMC-SIERRA, INC., AND FOR ITS CUSTOMERS' INTERNAL USE
35
PRELIMINARY DRIVER MANUAL PMC-990799 ISSUE 1
PM7350 S/UNI-DUPLEX DRIVER
S/UNI-DUPLEX DRIVER MANUAL
Member Name indRxBOC
Type DPX_IND_CB_FN
Description Indication callback function called by the DPR to forward a received valid BOC to the application Indication callback function called by the DPR when the driver must read cells from the Extract FIFOs A cell-type detector function that the driver uses to determine if a cell extracted is the last or first cell of a the message, and if it is CRC protected Contains the statistical counts for events and the number of interrupts Semaphore ID for the data structure. It is used for mutual exclusion access to the structure. Placeholder for future use
indRxCell
DPX_IND_CB_FN
pCellTypeFn
DPX_CELLTYPE_FN
sStatCounts
sDPX_STAT_COUNTS
lockId
DPX_SEM_ID
u4Reserved
UINT4
3.4
Interrupt Data Structures This section describes the data structures that the S/UNI-DUPLEX driver uses to queue interrupt context data for interrupt-enable bit-setting data.
3.4.1 Interrupt-Enable Data Structure The interrupt-enable bit-setting data is queued in the following structure.
PROPRIETARY AND CONFIDENTIAL TO PMC-SIERRA, INC., AND FOR ITS CUSTOMERS' INTERNAL USE
36
PRELIMINARY DRIVER MANUAL PMC-990799 ISSUE 1
PM7350 S/UNI-DUPLEX DRIVER
S/UNI-DUPLEX DRIVER MANUAL
Table 12: Interrupt Enables: sDPX_INT_ENBLS Member Name u1MasterEn u1RoolEn Type UINT1 UINT1 Description Master Interrupt Enable ROOLE bit (tracks change in ROOLV bit; located in clock monitor register) SCI-PHY/Any-PHY Input Interrupt Enables SCI-PHY/Any-PHY Output Interrupt Enable (CELLXFERRE bit) Microprocessor Cell Buffer Interrupt Control Receive Logical Channel FIFO Control (FOVRE bit) RXD1 and RXD2 Extract FIFO Control (UPF1OVRE bit) Receive HSS Interrupt Enables [2 bytes (RXD1, RXD2)] Receive HSS BOC Interrupt Enables [2 bytes (RXD1, RXD2)] Transmit Logical Channel FIFO Control (FOVRE bit) Receive Serial Indirect Channel Interrupt Enables
u1SciAnyPhyInpIntEn
UINT1
u1SciAnyPhyOutIntEn
UINT1
u1MicroCellBufCtrl
UINT1
u1RxLogChnlFifoCtrl
UINT1
u1RxHssExtractFifoOvr[2]
UINT1
u1RxHssIntEn[2]
UINT1
u1RxHssBocIntEn[2]
UINT1
u1TxLogChnlFifoCtrl
UINT1
u1RxClkSerIntEn[16]
UINT1
3.4.2 Interrupt-Context Data Structure The following structure passes interrupt context data from the interrupt servicing routine to the DPR.
PROPRIETARY AND CONFIDENTIAL TO PMC-SIERRA, INC., AND FOR ITS CUSTOMERS' INTERNAL USE
37
PRELIMINARY DRIVER MANUAL PMC-990799 ISSUE 1
PM7350 S/UNI-DUPLEX DRIVER
S/UNI-DUPLEX DRIVER MANUAL
Table 13: Interrupt Context: sDPX_INT_CTXT Member Name u1NumDevs Type UINT1 Description Number of devices for which interrupts have to be processed Array of size DPX_MAX_NUM_DEVS. The first u1NumDevs elements of this array contain the device handles for the devices for which interrupts have to be processed.
pu4DevHandles [DPX_MAX_NUM_DEVS]
UINT4*
3.5
Count Structures This section describes the data structures that the S/UNI-DUPLEX driver uses to store counts.
3.5.1 HSS Counts This section describes the data structure that the driver uses to store the number of HSS cells received and transmitted, and the number of cells that failed to be received. Table 14: HSS Counts: sDPX_HSS_CNTS Member Name u4RxCells[2] u4TxCells u1HcsErrs[2] Type UINT4 UINT4 UINT1 Description Cells received count [2 words (RXD1, RXD2)] Cells transmitted count HCS received count [2 bytes (RXD1, RXD2)]
3.5.2 Statistical Counts This section describes the data structure that the driver uses to store statistical counts.
PROPRIETARY AND CONFIDENTIAL TO PMC-SIERRA, INC., AND FOR ITS CUSTOMERS' INTERNAL USE
38
PRELIMINARY DRIVER MANUAL PMC-990799 ISSUE 1
PM7350 S/UNI-DUPLEX DRIVER
S/UNI-DUPLEX DRIVER MANUAL
Table 15: Statistical Counts: sDPX_STAT_COUNTS Member Name Count_Tx_Hss_Count_Overflow Type UINT4 Description Corresponds to register 0x61, bit 5 Corresponds to register 0x61, bit 6 Corresponds to register 0x3D, bit 0 Corresponds to register 0x5D, bit 0 Corresponds to register 0x0F, bit 2 Corresponds to register 0x0F, bit 1 Corresponds to register 0x0F, bit 0 Corresponds to register 0x14, bit 7 Corresponds to register 0x20, bit 4 Corresponds to register 0x20, bit 5 Corresponds to register 0x20, bit 7 Corresponds to register 0x04, bit 3 Corresponds to register 0x6B, bits 0,6 Corresponds to register 0x6B, bits 0,6
Count_Tx_Hss_Count_Updated
UINT4
Count_Rx_Lc_Fifo_Overflow
UINT4
Count_Tx_Lc_Fifo_Overflow
UINT4
Count_Phy_Input_Cell_Xfered
UINT4
Count_Invalid_SOC_Sequence
UINT4
Count_Phy_Input_Parity
UINT4
Count_Phy_Output_Error
UINT4
Count_Micro_Insert_Fifo_Ready
UINT4
Count_Micro_Insert_Fifo_Full
UINT4
Count_Extract_Cell_CRC_Error
UINT4
Count_Clock_Lock_Fail
UINT4
Count_RxSerChnl_Out_Of_Delin [16] Count_RxSerChnl_In_Delin[16]
UINT4
UINT4
PROPRIETARY AND CONFIDENTIAL TO PMC-SIERRA, INC., AND FOR ITS CUSTOMERS' INTERNAL USE
39
PRELIMINARY DRIVER MANUAL PMC-990799 ISSUE 1
PM7350 S/UNI-DUPLEX DRIVER
S/UNI-DUPLEX DRIVER MANUAL
Member Name Count_RxSerChnl_Fifo_Overflow [16] Count_RxSerChnl_HCS_Error[16]
Type UINT4
Description Corresponds to register 0x6B, bit 1 Corresponds to register 0x6B, bit 2 Corresponds to register 0x6B, bits 3,7 Corresponds to register 0x6B, bits 3,7 Corresponds to registers 0x31, 0x35, bit 0 Corresponds to registers: * * 0x43, 0x53, bit 0 0x41, 0x51, bit 0
UINT4
Count_RxSerChnl_Out_Of_Sync [16] Count_RxSerChnl_in_Sync[16]
UINT4
UINT4
Count_RxHss_Extract_Fifo_ Overflow[2] Count_RxHss_Loss_Of_Signal[2]
UINT4
UINT4
Count_RxHss_Signal_Detected [2]
UINT4
Corresponds to registers: * * 0x43, 0x53, bit 0 0x41, 0x51, bit 0
Count_RxHss_Out_Of_Delin[2]
UINT4
Corresponds to registers: * * 0x43, 0x53, bit 1 0x41, 0x51, bit 1
Count_RxHss_In_Delin[2]
UINT4
Corresponds to registers: * * 0x43, 0x53, bit 1 0x41, 0x51, bit 1
Count_RxHss_Active_Bit[2]
UINT4
Corresponds to registers: * * 0x43, 0x53, bit 2 0x41, 0x51, bit 2
Count_RxHss_No_Active_Bit[2]
UINT4
Corresponds to registers: * * 0x43, 0x53, bit 2 0x41, 0x51, bit 2
PROPRIETARY AND CONFIDENTIAL TO PMC-SIERRA, INC., AND FOR ITS CUSTOMERS' INTERNAL USE
40
PRELIMINARY DRIVER MANUAL PMC-990799 ISSUE 1
PM7350 S/UNI-DUPLEX DRIVER
S/UNI-DUPLEX DRIVER MANUAL
Member Name Count_RxHss_Out_Of_Sync[2]
Type UINT4
Description Corresponds to registers: * * 0x43, 0x53, bit 4 0x41, 0x51, bit 4
Count_RxHss_In_Sync[2]
UINT4
Corresponds to registers: * * 0x43, 0x53, bit 4 0x41, 0x51, bit 4
Count_RxHss_CRC8_Error[2]
UINT4
Corresponds to registers 0x43, 0x53, bit 3 Corresponds to registers 0x43, 0x53, bit 5 Corresponds to registers 0x43, 0x53, bit 6 Corresponds to registers 0x43, 0x53, bit 7 Corresponds to registers 0x19, 0x1B, bit 6 Corresponds to register 0x20, bit 6 Number of interrupts occurred for the device
Count_RxHss_HCS_Error[2]
UINT4
Count_RxHss_Count_Updated[2]
UINT4
Count_RxHss_Count_Overflow[2]
UINT4
Count_Rx_BOCs[2]
UINT4
Count_Extract_Cells
UINT4
Count_Interrupts
UINT4
PROPRIETARY AND CONFIDENTIAL TO PMC-SIERRA, INC., AND FOR ITS CUSTOMERS' INTERNAL USE
41
PRELIMINARY DRIVER MANUAL PMC-990799 ISSUE 1
PM7350 S/UNI-DUPLEX DRIVER
S/UNI-DUPLEX DRIVER MANUAL
PROPRIETARY AND CONFIDENTIAL TO PMC-SIERRA, INC., AND FOR ITS CUSTOMERS' INTERNAL USE
42
PRELIMINARY DRIVER MANUAL PMC-990799 ISSUE 1
PM7350 S/UNI-DUPLEX DRIVER
S/UNI-DUPLEX DRIVER MANUAL
4
APPLICATION INTERFACE FUNCTIONS The driver's API is a collection of high level functions that application programmers can call to configure, control, and monitor S/UNI-DUPLEX devices. Note: These functions are not re-entrant. This means that two application tasks cannot invoke the same API at the same time. However, the driver protects it's data structures from concurrent accesses by the application and the DPR task. The application interface also consists of callback functions. These callback functions notify the application of significant events that take place within the device and driver, such as: * * * Occurrence of critical errors Reception of cells Reception of valid BOCs
The duplexDPR routine invokes the indication callback functions. These execute in the context of the DPR task. Typically, these callback routines are implemented as simple message posting routines that post messages to an application task. However, the user can choose to implement the indication callback to perform processing within the DPR task context and return without sending any messages. In this case, ensure that the indication routine does not call any API function that changes the driver's state, such as duplexDelete. The indication routine should be non-blocking because the DPR task executes while interrupts are disabled. The DPR task is also responsible for re-enabling device interrupts once the deferred processing is complete. Many API functions change the device's state. For information about device states, see page 19. Figure 7 illustrates the external interfaces defined for the S/UNI-DUPLEX driver.
PROPRIETARY AND CONFIDENTIAL TO PMC-SIERRA, INC., AND FOR ITS CUSTOMERS' INTERNAL USE
43
PRELIMINARY DRIVER MANUAL PMC-990799 ISSUE 1
PM7350 S/UNI-DUPLEX DRIVER
S/UNI-DUPLEX DRIVER MANUAL
Figure 7: Application Interface
Application
Function Calls
Indication Callbacks
Application Interface
S/UNI-DUPLEX Driver
RTOS
Service Calls
Hardware Interrupts
Register Access
S/UNI-DUPLEX Device
4.1
Driver Initialization and Shutdown This section describes the API functions used to initialize and shutdown the driver's modules.
4.1.1 duplexModuleInit: Initializing Driver Modules This function performs module level initialization of the device driver. This involves allocating memory for the GDD and initializing the data structure. Valid States Side Effects Prototype Not applicable None INT4 duplexModuleInit(VOID)
PROPRIETARY AND CONFIDENTIAL TO PMC-SIERRA, INC., AND FOR ITS CUSTOMERS' INTERNAL USE
44
PRELIMINARY DRIVER MANUAL PMC-990799 ISSUE 1
PM7350 S/UNI-DUPLEX DRIVER
S/UNI-DUPLEX DRIVER MANUAL
Inputs Outputs Return Codes
None None DPX_SUCCESS DPX_ERR_MEM_ALLOC (memory allocation failure) DPX_ERR_MODULE_ALREADY_INIT
4.1.2 duplexModuleShutdown: Shutting Down Driver Modules This function performs module level shutdown of the driver. This involves deleting all devices controlled by the driver and deallocating the GDD. Valid States Side Effects Prototype Inputs Outputs Return Codes 4.2 All states Resets all the devices, and removes interrupt handle and DPR task VOID duplexModuleShutdown(VOID) None None None
Device Addition, Reset, and Deletion When you add a new S/UNI-DUPLEX device, the driver's device-addition functions allocate memory to store context information for new devices. The driver also applies a software reset to the device. The device deletion function deallocates device context memory during device shutdown.
4.2.1 duplexAdd: Adding Devices This function detects the new device in the hardware, gets the base address of the device, and allocates memory for the DDB. Then it stores the device's role (within your system's context) and returns the pointer to the DDB as a handle back to your system. You should use the device handle to identify the device on which the driver will perform the operation.
PROPRIETARY AND CONFIDENTIAL TO PMC-SIERRA, INC., AND FOR ITS CUSTOMERS' INTERNAL USE
45
PRELIMINARY DRIVER MANUAL PMC-990799 ISSUE 1
PM7350 S/UNI-DUPLEX DRIVER
S/UNI-DUPLEX DRIVER MANUAL
This function also reads the configuration pins status register to determine the configuration of the SCI-PHY/Any-PHY and clocked serial-data interfaces. The driver uses this information to set the device mode in the DDB. Valid States Side Effects Prototype Inputs DPX_EMPTY This function puts the device in the DPX_PRESENT state. The function applies a software reset to the device. INT4 duplexAdd(DPX_USR_CTXT usrCtxt, DUPLEX *pDuplex) usrCtxt: Pointer to context information (maintained by your system) for the device being added pDuplex: Pointer to the S/UNI-DUPLEX device handle. The variable type, DUPLEX, is actually the following type, which you define: * #define DUPLEX (void *)
Outputs
This prevents the application from accessing the DDB directly. Return Codes DPX_SUCCESS DPX_ERR_INVALID_STATE (invalid device state) DPX_ERR_DEV_NOT_DETECTED (device was not detected) DPX_ERR_MEM_ALLOC (memory allocation failure) DPX_ERR_DEV_ID_TYPE (invalid device ID and/or type) 4.2.2 duplexReset: Resetting Devices This function applies a software reset to the S/UNI-DUPLEX device. It also resets all of the device's context information in the DDB (except for the initialization vector, which it leaves unmodified). Typically, the driver calls this function during device shutdown, or before re-initializing the device with an initialization vector. Valid States Side Effects All states except DPX_EMPTY This function puts the device in the DPX_PRESENT state. Therefore, the driver must initialize the device after a reset.
PROPRIETARY AND CONFIDENTIAL TO PMC-SIERRA, INC., AND FOR ITS CUSTOMERS' INTERNAL USE
46
PRELIMINARY DRIVER MANUAL PMC-990799 ISSUE 1
PM7350 S/UNI-DUPLEX DRIVER
S/UNI-DUPLEX DRIVER MANUAL
Prototype Inputs Outputs Return Codes
INT4 duplexReset(DUPLEX duplex) duplex: Pointer to DDB that contains device context information maintained by the driver None DPX_SUCCESS DPX_ERR_INVALID_DEVICE (invalid device handle)
4.2.3 duplexRemoteReset: Resetting Other Devices This function resets other devices by driving the RSTOB output pin of the S/UNI-DUPLEX device low and then back to a high impedance state. It does this by setting and resetting the RESET0 pin in the master configuration register. Valid States Side Effects Prototype Inputs All states except DPX_EMPTY None INT4 duplexRemoteReset(DUPLEX duplex) duplex: Pointer to DDB that contains device context information maintained by the driver None DPX_SUCCESS DPX_ERR_INVALID_DEVICE (invalid device handle) 4.2.4 duplexDelete: Deleting Devices This function removes the specified device from the list of devices controlled by the S/UNI-DUPLEX driver. Deleting a device involves deallocating the DDB for that device. Valid States Side Effects DPX_PRESENT This function changes the device state to DPX_EMPTY
Outputs Return Codes
PROPRIETARY AND CONFIDENTIAL TO PMC-SIERRA, INC., AND FOR ITS CUSTOMERS' INTERNAL USE
47
PRELIMINARY DRIVER MANUAL PMC-990799 ISSUE 1
PM7350 S/UNI-DUPLEX DRIVER
S/UNI-DUPLEX DRIVER MANUAL
Prototype Inputs Outputs Return Codes
INT4 duplexDelete(DUPLEX duplex) duplex: Device handle used by the driver to access context information for the device (DDB) None DPX_SUCCESS DPX_ERR_INVALID_DEVICE (invalid device handle) DPX_ERR_INVALID_STATE (invalid device state)
4.3
Reading from and Writing to Devices This section describes the API functions used to read from and write to S/UNI-DUPLEX devices. Their tasks include reading from and writing to the registers of a device.
4.3.1 duplexRead: Reading from Device Registers This function can read from a register of a specific S/UNI-DUPLEX device by providing the register identifier. This function derives the actual address location based on the device handle and register identifier inputs. It then reads the contents of this address location using the system specific macro, sysDuplexRawRead. Prototype Inputs INT4 duplexRead(DUPLEX duplex, UINT2 u2RegId, UINT1 *pu1Val) duplex: Pointer to device context information u2RegId: Register identifier Outputs Return Codes pu1Val: Register value DPX_SUCCESS DPX_ERR_INVALID_DEVICE (invalid device handle) DPX_ERR_EXCEED_REG_RANGE (u2RegId exceeds the register range)
PROPRIETARY AND CONFIDENTIAL TO PMC-SIERRA, INC., AND FOR ITS CUSTOMERS' INTERNAL USE
48
PRELIMINARY DRIVER MANUAL PMC-990799 ISSUE 1
PM7350 S/UNI-DUPLEX DRIVER
S/UNI-DUPLEX DRIVER MANUAL
4.3.2 duplexWrite: Writing to Device Registers This function can write to a register of a specific S/UNI-DUPLEX device by providing the register identifier. This function derives the actual address location based on the device handle and register identifier inputs. It then writes the contents of this address location using the system specific macro, sysDuplexRawWrite. Prototype Inputs INT4 duplexWrite(DUPLEX duplex, UINT2 u2RegId, UINT1 u1Val) duplex: Pointer to device context information u2RegId: Register identifier u1Val: Value to be written Outputs Return Codes None DPX_SUCCESS DPX_ERR_INVALID_DEVICE (invalid device handle) DPX_ERR_EXCEED_REG_RANGE (u2RegId exceeds the register range) 4.4 Device Initialization This section describes the API functions used to initialize S/UNI-DUPLEX devices. Their tasks include initializing the device based on the initialization vector passed by the application. They also install and remove the indication callback functions that duplexDPR calls. 4.4.1 duplexInit: Initializing Devices This function initializes the device based on the initialization vector passed by the application. The driver validates this initialization vector and then stores it in the device's DDB. The driver then configures the device registers accordingly. Valid States Side Effects DPX_PRESENT This function puts the device in the DPX_INIT state
PROPRIETARY AND CONFIDENTIAL TO PMC-SIERRA, INC., AND FOR ITS CUSTOMERS' INTERNAL USE
49
PRELIMINARY DRIVER MANUAL PMC-990799 ISSUE 1
PM7350 S/UNI-DUPLEX DRIVER
S/UNI-DUPLEX DRIVER MANUAL
Prototype Inputs
INT4 duplexInit(DUPLEX duplex, sDPX_INIT_VECT, sInitVector) duplex: Pointer to DDB that contains device context information maintained by the driver sInitVector: Initialization vector that the driver uses to program the device registers
Outputs Return Codes
None DPX_SUCCESS DPX_ERR_INVALID_DEVICE (invalid device handle) DPX_ERR_INVALID_STATE (invalid device state) DPX_ERR_INVALID_INIT_VECTOR (invalid initialization vector) DPX_ERR_INDIRECT_CHANNEL_BUSY (Clocked serial channel is busy and causes timeout when its registers are accessed)
4.4.2 duplexInstallIndFn: Installing Indication Callback Functions This function installs the indication callback functions (which you define) that duplexDPR calls. The function pointer is stored in the device context structure (the DDB). Valid States Side Effects Prototype DPX_INIT None INT4 duplexInstallIndFn(DUPLEX duplex, eDPX_CB_TYPE eCbType, DPX_IND_CB_FN pCbFn)
PROPRIETARY AND CONFIDENTIAL TO PMC-SIERRA, INC., AND FOR ITS CUSTOMERS' INTERNAL USE
50
PRELIMINARY DRIVER MANUAL PMC-990799 ISSUE 1
PM7350 S/UNI-DUPLEX DRIVER
S/UNI-DUPLEX DRIVER MANUAL
Inputs
duplex: Pointer to DDB that contains device context information maintained by the driver eCbType: Identifies the callback being installed, which can be one of: * * * DPX_CB_NOTIFY DPX_CB_RX_BOC DPX_CB_RX_CELL
pCbFn: Callback function that the driver is installing Outputs Return Codes None DPX_SUCCESS DPX_ERR_INVALID_DEVICE (invalid device handle) DPX_ERR_INVALID_CB_TYPE (invalid callback function type) 4.4.3 duplexRemoveIndFn: Removing Indication Callback Functions This function removes the indication callback functions (which you define) that duplexDPR calls. Valid States Side Effects Prototype Inputs DPX_INIT The driver will no longer report events to the application. INT4 duplexRemoveIndFn(DUPLEX duplex, eDPX_CB_TYPE eCbType) duplex: Pointer to DDB that contains device context information maintained by the driver eCbType: Identifies the callback being installed, which can be one of: * * * Outputs DPX_CB_NOTIFY DPX_CB_RX_BOC DPX_CB_RX_CELL
None
PROPRIETARY AND CONFIDENTIAL TO PMC-SIERRA, INC., AND FOR ITS CUSTOMERS' INTERNAL USE
51
PRELIMINARY DRIVER MANUAL PMC-990799 ISSUE 1
PM7350 S/UNI-DUPLEX DRIVER
S/UNI-DUPLEX DRIVER MANUAL
Return Codes
DPX_SUCCESS DPX_ERR_INVALID_DEVICE (invalid device handle) DPX_ERR_INVALID_CB_TYPE (invalid callback function type)
4.5
Device Activation and Deactivation This section describes the API functions used to activate and deactivate S/UNI-DUPLEX devices. These functions set the device interrupts and other global enables.
4.5.1 duplexActivate: Activating Devices This function activates the S/UNI-DUPLEX device by preparing it for normal operation. This involves enabling device interrupts and other global enables (for example, the HSS link transmitter). Valid States Side Effects Prototype Inputs DPX_INIT Puts the device in DPX_ACTIVE state. INT4 duplexActivate(DUPLEX duplex) duplex: Pointer to DDB that contains device context information maintained by the driver None DPX_SUCCESS DPX_ERR_INVALID_DEVICE (invalid device handle) DPX_ERR_INVALID_STATE (invalid device state) 4.5.2 duplexDeactivate: Deactivating Devices This function de-activates the S/UNI-DUPLEX device and removes it from normal operation. This involves disabling device interrupts and other global disables (for example, the HSS link transmitter).
Outputs Return Codes
PROPRIETARY AND CONFIDENTIAL TO PMC-SIERRA, INC., AND FOR ITS CUSTOMERS' INTERNAL USE
52
PRELIMINARY DRIVER MANUAL PMC-990799 ISSUE 1
PM7350 S/UNI-DUPLEX DRIVER
S/UNI-DUPLEX DRIVER MANUAL
Valid States Side Effects Prototype Inputs Outputs Return Codes
DPX_ACTIVE Puts the device in DPX_INIT state. INT4 duplexDeactivate(DUPLEX duplex) duplex: Pointer to DDB that contains device context information maintained by the driver None DPX_SUCCESS DPX_ERR_INVALID_DEVICE (invalid device handle) DPX_ERR_INVALID_STATE (invalid device state)
4.6
Device Diagnostics This section describes the API functions used to diagnose the S/UNI-DUPLEX device. Their tasks include: * * * Verifying the correctness of the microprocessor's access to the device registers Enabling or disabling a diagnostic or line loopback on the HSS interfaces Monitoring the activity of the device's clocks
4.6.1 duplexRegisterTest: Verifying Device Register Access This function verifies the correctness of the microprocessor's access to the device registers by writing values to the writable registers and reading them back. Valid States Side Effects DPX_PRESENT Puts the device in the DPX_PRESENT state after the test. Therefore, the device should be re-initialized after calling this function. INT4 duplexRegisterTest(DUPLEX duplex) duplex: Pointer to DDB that contains device context information maintained by the driver
Prototype Inputs
PROPRIETARY AND CONFIDENTIAL TO PMC-SIERRA, INC., AND FOR ITS CUSTOMERS' INTERNAL USE
53
PRELIMINARY DRIVER MANUAL PMC-990799 ISSUE 1
PM7350 S/UNI-DUPLEX DRIVER
S/UNI-DUPLEX DRIVER MANUAL
Outputs Return Codes
None DPX_SUCCESS DPX_ERR_INVALID_DEVICE (invalid device handle) DPX_ERR_INVALID_STATE (invalid device state) DPX_FAILURE (test failed)
4.6.2 duplexLoopback: Enabling/Disabling Diagnostic or Line Loopback This function enables or disables a diagnostic or line loopback on the HSS interfaces. Valid States Side Effects Prototype Inputs All states except DPX_EMPTY None INT4 duplexLoopback(DUPLEX duplex, UINT1 u1HssLnkId, UINT1 u1LpbkType, UINT1 u1Enable) duplex: Pointer to DDB that contains device context information maintained by the driver u1HssLnkId: HSS link identifier. Valid identifiers are DPX_RXD1 and DPX_RXD2. u1LpbkType: Type of loopback. It can be DPX_DIAG_LPBK or DPX_LINE_LPBK. u1Enable: Loopback operation requested. It can be DPX_LPBK_SET or DPX_LPBK_RESET. Outputs None
PROPRIETARY AND CONFIDENTIAL TO PMC-SIERRA, INC., AND FOR ITS CUSTOMERS' INTERNAL USE
54
PRELIMINARY DRIVER MANUAL PMC-990799 ISSUE 1
PM7350 S/UNI-DUPLEX DRIVER
S/UNI-DUPLEX DRIVER MANUAL
Return Codes
DPX_SUCCESS DPX_ERR_INVALID_DEVICE (invalid device handle) DPX_ERR_INVALID_STATE (invalid device state) DPX_ERR_INVALID_LPBK_TYPE (invalid loopback type) DPX_ERR_INVALID_HSS_ID (invalid HSS-link identifier) DPX_ERR_INVALID_FLAG (invalid loopback flag)
4.6.3 duplexGetClockStatus: Monitoring Device Clocks This function monitors the activity of the S/UNI-DUPLEX device clocks. It reads the contents of the clock monitor register and provides the status of each clock in a bit vector format. The application should call this function periodically to check if the clock signals are making low to high transitions. Valid States Side Effects Prototype Inputs All states except DPX_EMPTY None INT4 duplexGetClockStatus(DUPLEX duplex, UINT1 *pu1ClkStat) duplex: Pointer to DDB that contains device context information maintained by the driver pu1ClkStat: Contains the following bit vector that indicates the active/inactive status of the S/UNI-DUPLEX device clocks. A one in the bit position indicates that the clock is active. A zero indicates that the clock is inactive. * * * Return Codes Bit 0: Input FIFO clock (IFCLK) (SCI-PHY/Any-PHY Interface) Bit 1: Output FIFO clock (OFCLK) (SCI-PHY/Any-PHY Interface) Bit 2: Reference clock input (REFCLK)
Outputs
DPX_SUCCESS DPX_ERR_INVALID_DEVICE (invalid device handle)
PROPRIETARY AND CONFIDENTIAL TO PMC-SIERRA, INC., AND FOR ITS CUSTOMERS' INTERNAL USE
55
PRELIMINARY DRIVER MANUAL PMC-990799 ISSUE 1
PM7350 S/UNI-DUPLEX DRIVER
S/UNI-DUPLEX DRIVER MANUAL
4.7
HSS Link Configuration This section describes the API functions used to configure HSS links. Their tasks include: * * * * Retrieving the contents of the specified HSS-link's configuration registers Configuring or modifying the contents of the specified HSS-link's configuration registers Getting a snapshot of the state of the eight HSS links for the specified device Retrieving the logical-channel address information for all HSS links of the specified device
4.7.1 duplexHssActiveLnkGetCfg: Getting HSS-Link Selection Method Information This function obtains information about the active-link selection method configured in the Master Configuration register. This information states whether the active link is set automatically by the S/UNI-DUPLEX, or if it was set manually by the application. If the active link was set manually, then this information states what the manual setting is. Valid States Side Effects Prototype Inputs DPX_INIT, DPX_ACTIVE None INT4 duplexHssActiveLnkGetCfg(DUPLEX duplex, eHSS_LNK_SEL *peLnkSel) duplex: Pointer to DDB that contains device context information maintained by the driver peLnkSel: Specifies the HSS link selection. It can be one of: * * * Return Codes DPX_RX_HSS_LNK_SELECT_AUTO DPX_RX_HSS_LNK_SELECT_RXD1 DPX_RX_HSS_LNK_SELECT_RXD2
Outputs
DPX_SUCCESS DPX_ERR_INVALID_DEVICE (invalid device handle) DPX_ERR_INVALID_STATE (invalid device state)
PROPRIETARY AND CONFIDENTIAL TO PMC-SIERRA, INC., AND FOR ITS CUSTOMERS' INTERNAL USE
56
PRELIMINARY DRIVER MANUAL PMC-990799 ISSUE 1
PM7350 S/UNI-DUPLEX DRIVER
S/UNI-DUPLEX DRIVER MANUAL
4.7.2 duplexHssActiveLnkSetCfg: Setting Active HSS Links This function sets the active HSS link of the S/UNI-DUPLEX device. The active link can be set automatically by the device or set manually by the application. Valid States Side Effects Prototype Inputs DPX_INIT, DPX_ACTIVE None INT4 duplexHssActiveLnkSetCfg(DUPLEX duplex, eHSS_LNK_SEL eLnkSel) duplex: Pointer to DDB that contains device context information maintained by the driver eLnkSel: Specifies the HSS link selection, which can be one of: * * * Outputs Return Codes DPX_RX_HSS_LNK_SELECT_AUTO DPX_RX_HSS_LNK_SELECT_RXD1 DPX_RX_HSS_LNK_SELECT_RXD2
None DPX_SUCCESS DPX_ERR_INVALID_DEVICE (invalid device handle) DPX_ERR_INVALID_STATE (invalid device state)
4.7.3 duplexHssGetConfig: Getting HSS-Link Configuration Information This function retrieves the contents of the specified HSS link's configuration registers. With one call, this function can retrieve the value of individual configuration registers as well as the entire configuration register set. Valid States Side Effects Prototype DPX_INIT, DPX_ACTIVE None INT4 duplexHssGetConfig(DUPLEX duplex, eDPX_HSS_REG eHssRegId, sDPX_HSS_REGS *psHssRegs)
PROPRIETARY AND CONFIDENTIAL TO PMC-SIERRA, INC., AND FOR ITS CUSTOMERS' INTERNAL USE
57
PRELIMINARY DRIVER MANUAL PMC-990799 ISSUE 1
PM7350 S/UNI-DUPLEX DRIVER
S/UNI-DUPLEX DRIVER MANUAL
Inputs
duplex: Pointer to DDB that contains device context information maintained by the driver eHssRegId: Specifies the register holding the value the driver will retrieve. It can be one of: * * * * * * DPX_RX_HSS_CFG_RXD0 DPX_RX_HSS_CFG_RXD1 DPX_RX_HSS_CELL_FILTER_CFG_RXD0 DPX_RX_HSS_CELL_FILTER_CFG_RXD1 DPX_TX_HSS_CFG DPX_ALL_HSS_REGS
Note: The logical-channel base address and address range are retrieved together. In addition, the driver can retrieve all configuration registers at once using DPX_ALL_HSS_REGS. Outputs psHssRegs: Contents of the specified HSS-link control register(s) output by this function. These contents are valid only if the function returns DPX_SUCCESS. Further, only those fields of this structure are valid that have been requested using the input parameter, eHssRegId. DPX_SUCCESS DPX_ERR_INVALID_DEVICE (invalid device handle) DPX_ERR_INVALID_STATE (invalid device state) DPX_ERR_INVALID_REG_ID (invalid register ID) 4.7.4 duplexHssSetConfig: Modifying HSS-Link Configuration Information This function sets up or modifies the contents of the specified HSS-link's configuration registers. With one call, this function can set the value of individual configuration registers as well as the entire configuration register set. Valid States Side Effects DPX_INIT, DPX_ACTIVE None
Return Codes
PROPRIETARY AND CONFIDENTIAL TO PMC-SIERRA, INC., AND FOR ITS CUSTOMERS' INTERNAL USE
58
PRELIMINARY DRIVER MANUAL PMC-990799 ISSUE 1
PM7350 S/UNI-DUPLEX DRIVER
S/UNI-DUPLEX DRIVER MANUAL
Prototype
INT4 duplexHssSetConfig(DUPLEX duplex, eDPX_HSS_REG eHssRegId, sDPX_HSS_REGS *psHssRegs) duplex: Pointer to DDB that contains device context information maintained by the driver eHssRegId: Specifies the register with the value the driver will write. It can be one of: * * * * * * DPX_RX_HSS_CFG_RXD0 DPX_RX_HSS_CFG_RXD1 DPX_RX_HSS_CELL_FILTER_CFG_RXD0 DPX_RX_HSS_CELL_FILTER_CFG_RXD1 DPX_TX_HSS_CFG DPX_ALL_HSS_REGS
Inputs
Note: The logical channel base address and address range have to be set together. In addition, the driver can set all configuration registers at once using DPX_ALL_HSS_REGS. psHssRegs: Contents of the specified HSS-link control register(s) to be set. The only fields in this structure that will be set are those that the driver has requested using eHssRegId. Outputs Return Codes None DPX_SUCCESS DPX_ERR_INVALID_DEVICE (invalid device handle) DPX_ERR_INVALID_STATE (invalid device state) DPX_ERR_INVALID_REG_ID (invalid register ID) 4.8 HSS-Link Cell Insertion and Extraction This section describes the API functions used to insert cells into, and extract cells from, HSS-links. Their tasks include: * * Transmitting a cell on a specified HSS-link 's control channel Extracting a cell received on a specified HSS-link 's control channel
PROPRIETARY AND CONFIDENTIAL TO PMC-SIERRA, INC., AND FOR ITS CUSTOMERS' INTERNAL USE
59
PRELIMINARY DRIVER MANUAL PMC-990799 ISSUE 1
PM7350 S/UNI-DUPLEX DRIVER
S/UNI-DUPLEX DRIVER MANUAL
* * *
Returning the contents of the microprocessor extract FIFO ready register Enabling the interrupt indication for a cell's reception Installing a callback function that determines the type of cell being extracted
4.8.1 duplexInsertCell: Inserting Cells into HSS Links This function transmits a cell on the control channel of both the active and standby HSS links. This function can send messages, which you define, over the HSS links. If the message is longer than the length of a cell's payload, then the application should segment the message into 48 byte cells. Call this function repeatedly until all the cells that constitute the message have been transmitted. Optionally, a 32-bit CRC can protect messages. The CRC accumulates each time a cell belonging to the message is sent. For the last cell of the message (indicated by the application), the CRC is inserted into the last four bytes of the cell's payload. Message interleaving (over different circuits in the same control channel) is allowed. For CRC-32 protected messages, message interleaving requires the application to save the intermediate CRC-32 value output by this function, if a cell has to be sent out on another control channel or another circuit on the same control channel. Valid States Side Effects DPX_ACTIVE You should give cell reception higher priority than cell transmission to prevent extract FIFO overflow. In other words, all cells of a received message should be extracted before switching context. INT4 duplexInsertCell(DUPLEX duplex, sDPX_CELL_HDR *psCellHdr, UINT1 *pu1CellPyld, sDPX_CELL_CTRL *psCtrl)
Prototype
PROPRIETARY AND CONFIDENTIAL TO PMC-SIERRA, INC., AND FOR ITS CUSTOMERS' INTERNAL USE
60
PRELIMINARY DRIVER MANUAL PMC-990799 ISSUE 1
PM7350 S/UNI-DUPLEX DRIVER
S/UNI-DUPLEX DRIVER MANUAL
Inputs
duplex: Pointer to DDB that contains device context information maintained by the driver psCellHdr: Pointer to the cell header structure that contains the two prepend bytes that you define (optional), H1-H4 bytes, and the H5 (optional) and UDF (optional) bytes. The driver uses the optional bytes based on the TX HSS configuration register contents. pu1CellPyld: Pointer to first byte of cell payload (48 contiguous bytes) psCtrl->u1CrcFlg: Control flag containing the following bit vectors: * * * Bit 0: Flag for CRC protection flag Bit 1: Flag for first cell of a CRC protected message Bit 2: Flag for last cell of a CRC protected message
psCtrl->u4Crc32Prev: Used to restore previously saved CRC-32 value output by this function. Only applicable if bit 0 of psCtrl->u1CrcFlg is set. Outputs psCtrl->u4Crc32: Used to output CRC-32 value after writing a cell. The driver then passes this value back as an input parameter (psCtrl->u4Crc32Prev) for the next cell to be transmitted on the same control channel connection. DPX_SUCCESS DPX_ERR_INVALID_DEVICE (invalid device handle) DPX_ERR_INVALID_STATE (invalid device state) DPX_ERR_CELL_TX_BUSY (cell transmission port busy) 4.8.2 duplexExtractCell: Extracting Cells from HSS Links This function extracts a cell received on a specified HSS-link 's control channel. This function also receives messages, which you define, that can span multiple cells. The application must call this function once for each cell that constitutes the message.
Return Codes
PROPRIETARY AND CONFIDENTIAL TO PMC-SIERRA, INC., AND FOR ITS CUSTOMERS' INTERNAL USE
61
PRELIMINARY DRIVER MANUAL PMC-990799 ISSUE 1
PM7350 S/UNI-DUPLEX DRIVER
S/UNI-DUPLEX DRIVER MANUAL
If the incoming message contains a CRC-32 field at the end, then the driver can perform a CRC check over the body of the message. The function also provides the header information of the cell to the calling function. Valid States Side Effects DPX_ACTIVE You should give cell reception a higher priority than cell transmission to prevent extract FIFO overflow. In other words, all cells of a received message should be extracted before switching context. INT4 duplexExtractCell(DUPLEX duplex, UINT1 u1HssLnkId, sDPX_CELL_HDR *psCellHdr, UINT1 *pu1CellPyld, sDPX_CELL_CTRL *psCtrl) duplex: Pointer to DDB that contains device context information maintained by the driver u1HssLnkId: HSS link identifier. Valid identifiers are DPX_RXD1 and DPX_RXD2. Outputs psCellHdr: Pointer to the cell header-data received pu1CellPyld: Pointer to first byte of cell payload 48 contiguous bytes) psCtrl->u4Crc32: Used to output CRC-32 value after reading a cell. The driver then passes this value back as an input parameter (psCtrl->u4Crc32Prev) for the next cell to be extracted on the same control channel connection. psCtrl->u1CrcFlg: This is a control flag. Contains the following bit vector: * * * Bit 0: CRC protection flag Bit 1: Flag for first cell of a CRC protected message Bit 2: Flag for last cell of a CRC protected message
Prototype
Inputs
PROPRIETARY AND CONFIDENTIAL TO PMC-SIERRA, INC., AND FOR ITS CUSTOMERS' INTERNAL USE
62
PRELIMINARY DRIVER MANUAL PMC-990799 ISSUE 1
PM7350 S/UNI-DUPLEX DRIVER
S/UNI-DUPLEX DRIVER MANUAL
Return Codes
DPX_SUCCESS DPX_ERR_INVALID_DEVICE (invalid device handle) DPX_ERR_INVALID_STATE (invalid device state) DPX_ERR_INVALID_LNK_ID (invalid link ID) DPX_ERR_CB_FN_NOT_INSTALLED (callback function is not installed yet) DPX_ERR_CELL_RX_CRC (cell reception CRC error)
4.8.3 duplexCheckExtractFifos: Getting Contents of the Extract-FIFO-Ready Register This function returns the contents of the microprocessor extract-FIFO-ready register. This function can check if there are any cells to extract from the extract FIFOs. Valid States Side Effects Prototype Inputs Outputs DPX_ACTIVE None UINT4 duplexCheckExtractFifos(DUPLEX duplex, UINT1 *pu1CellReady) duplex: Pointer to DDB that contains device context information maintained by the driver pu1CellReady: Contains the following bit vector, which represents the state of each extract FIFO: * Bit 0: * * If value is 1, then RXD1 has at least one cell ready for extraction * If value is 0, then no cells present Bit 1: * * If value is 1, then RXD2 has at least one cell ready for extraction If value is 0, then no cells present
PROPRIETARY AND CONFIDENTIAL TO PMC-SIERRA, INC., AND FOR ITS CUSTOMERS' INTERNAL USE
63
PRELIMINARY DRIVER MANUAL PMC-990799 ISSUE 1
PM7350 S/UNI-DUPLEX DRIVER
S/UNI-DUPLEX DRIVER MANUAL
Return Codes
DPX_SUCCESS DPX_ERR_INVALID_DEVICE (invalid device handle) DPX_ERR_INVALID_STATE (invalid device state)
4.8.4 duplexEnableRxCellInd: Enabling the Received Cell Indicator This function enables the interrupt indication in the device for the reception of a cell. The application calls this function after it has responded to a previous indication by extracting all received cells (using multiple duplexExtractCell calls). The application task can now re-enable this indication and wait for the arrival of more cells. Valid States Side Effects Prototype Inputs DPX_ACTIVE None INT4 duplexEnableRxCellInd(DUPLEX duplex) duplex: Pointer to DDB that contains device context information maintained by the driver None DPX_SUCCESS DPX_ERR_INVALID_DEVICE (invalid device handle) DPX_ERR_INVALID_STATE (invalid device state) 4.8.5 duplexInstallCellTypeFn: Installing Callback Functions This function can install a callback function (which you define) that the driver uses to determine the type of cell it is extracting. The detector function takes a cell header as the input argument and returns a cell type byte and the previous CRC-32 value for the same message of the same logical channel. Valid States Side Effects DPX_INIT, DPX_ACTIVE None
Outputs Return Codes
PROPRIETARY AND CONFIDENTIAL TO PMC-SIERRA, INC., AND FOR ITS CUSTOMERS' INTERNAL USE
64
PRELIMINARY DRIVER MANUAL PMC-990799 ISSUE 1
PM7350 S/UNI-DUPLEX DRIVER
S/UNI-DUPLEX DRIVER MANUAL
Prototype Inputs
duplexInstallCellTypeFn(DUPLEX duplex, DPX_EOM_FN pCellTypeFn) duplex: Pointer to DDB that contains device context information maintained by the driver pCellTypeFn: Pointer to the EOM detector function. The prototype of this function is: * UINT1 pCellTypeFn(UINT1 *pu1Hdr, UINT4 *pu4Crc32Prev)
In the detector function, pu1Hdr is the pointer to the first byte of the cell header's eight bytes. pu4Crc32Prev is the accumulated CRC for the previous cells received for the same message. Outputs Return Codes None DPX_SUCCESS DPX_ERR_INVALID_DEVICE (invalid device handle) DPX_ERR_INVALID_STATE (invalid device state) 4.9 BOC Transmission and Reception This section describes the API functions used to transmit and receive bit-oriented code (BOC). Their tasks include transmitting the specified BOC on the specified HSS link, and reading the BOC received on a HSS link 4.9.1 duplexTxBOC: Transmitting BOC This function transmits the specified BOC on the specified HSS link. In the case of transmitting a loopback activate-BOC code, the RDIDIS register bit should be set to logic 1 before the transmission. This prevents a pre-emptive remote-defect-indication (RDI) code from being sent. Valid States Side Effects Prototype DPX_ACTIVE None INT4 duplexTxBOC(DUPLEX duplex, UINT1 u1HssLnkId, UINT1 u1Code)
PROPRIETARY AND CONFIDENTIAL TO PMC-SIERRA, INC., AND FOR ITS CUSTOMERS' INTERNAL USE
65
PRELIMINARY DRIVER MANUAL PMC-990799 ISSUE 1
PM7350 S/UNI-DUPLEX DRIVER
S/UNI-DUPLEX DRIVER MANUAL
Inputs
duplex: Pointer to DDB that contains device context information maintained by the driver u1HssLnkId: HSS link identifier. Valid identifiers are DPX_RXD1 and DPX_RXD2. u1Code: BOC to be transmitted. Valid BOCs are: * * * * * * * 000000b (RDI) 000001b (loopback activate) 000010b (loopback deactivate) 000011b (remote reset activate) 000100b (remote reset not activate) 010001b to 111110b (defined by you) 111111b (idle code)
Outputs Return Codes
None DPX_SUCCESS DPX_ERR_INVALID_DEVICE (invalid device handle) DPX_ERR_INVALID_STATE (invalid device state) DPX_ERR_INVALID_LNK_ID (invalid link ID) DPX_ERR_INVALID_BOC (invalid BOC)
4.9.2 duplexRxBOC: Reading from Received BOC This function can read BOC received on a HSS link. Valid States Side Effects DPX_ACTIVE This function reads from the receive-BOC status register. The application should call this function inside the indDuplexRxBOC indication-callback function. This function clears the status bits (IDLEI and BOCI) in the BOC status register. INT4 duplexRxBOC(DUPLEX duplex, UINT1 u1HssLnkId, UINT1 *pu1Code)
Prototype
PROPRIETARY AND CONFIDENTIAL TO PMC-SIERRA, INC., AND FOR ITS CUSTOMERS' INTERNAL USE
66
PRELIMINARY DRIVER MANUAL PMC-990799 ISSUE 1
PM7350 S/UNI-DUPLEX DRIVER
S/UNI-DUPLEX DRIVER MANUAL
Inputs
duplex: Pointer to DDB that contains device context information maintained by the driver u1HssLnkId: HSS link identifier. Valid identifiers are DPX_RXD1 and DPX_RXD2.
Outputs
pu1Code: Pointer to BOC to be received. Valid BOCs are: * * * * * * * 000000b (RDI) 000001b (loopback activate) 000010b (loopback deactivate) 000011b (remote reset activate) 000100b (remote reset deactivate) 010001b to 111110b (defined by you) 111111b (idle code)
Return Codes
DPX_SUCCESS DPX_ERR_INVALID_DEVICE (invalid device handle) DPX_ERR_INVALID_STATE (invalid device state) DPX_ERR_INVALID_LNK_ID (invalid link ID) DPX_ERR_INVALID_BOC (invalid BOC)
4.9.3 duplexSetAutoRDITx: Transmitting Remote-Defect Indication Code Words Enables/disables the automatic transmission of an RDI code word on the specified HSS link. Valid States Side Effects Prototype DPX_INIT, DPX_ACTIVE None INT4 duplexSetAutoRDITx(DUPLEX duplex, UINT1 u1HssLnkId, UINT1 u1DisableFlg)
PROPRIETARY AND CONFIDENTIAL TO PMC-SIERRA, INC., AND FOR ITS CUSTOMERS' INTERNAL USE
67
PRELIMINARY DRIVER MANUAL PMC-990799 ISSUE 1
PM7350 S/UNI-DUPLEX DRIVER
S/UNI-DUPLEX DRIVER MANUAL
Inputs
duplex: Pointer to DDB that contains device context information maintained by the driver u1HssLnkId: HSS link identifier. Valid identifiers are DPX_RXD1 and DPX_RXD2. u1DisableFlg: 1 enables auto transmission of RDI. 0 disables auto transmission of RDI.
Outputs Return Codes
None DPX_SUCCESS DPX_ERR_INVALID_DEVICE (invalid device handle) DPX_ERR_INVALID_STATE (invalid device state) DPX_ERR_INVALID_LNK_ID (invalid link ID)
4.9.4 duplexSciAnyPhyGetConfig: Getting SCI-PHY/Any-PHY Configuration Information This function retrieves the contents of the S/UNI-DUPLEX SCI-PHY/Any-PHY configuration registers. It can retrieve the value of individual configuration registers. Alternatively, it can retrieve the entire configuration register set with one call. Valid States Side Effects Prototype DPX_INIT, DPX_ACTIVE None INT4 duplexSciAnyPhyGetConfig(DUPLEX duplex, eDPX_SCI_ANY_PHY_REG eSciAnyPhyRegId, sDPX_SCI_ANY_PHY_REGS *psSciAnyPhyRegs)
PROPRIETARY AND CONFIDENTIAL TO PMC-SIERRA, INC., AND FOR ITS CUSTOMERS' INTERNAL USE
68
PRELIMINARY DRIVER MANUAL PMC-990799 ISSUE 1
PM7350 S/UNI-DUPLEX DRIVER
S/UNI-DUPLEX DRIVER MANUAL
Inputs
duplex: Pointer to DDB that contains device context information maintained by the driver eSciAnyPhyRegId: Specifies the register containing the value to be retrieved. It can be one of: * * * * * * * * * * * * DPX_SCI_ANY_PHY_EXT_ADDR_MATCH DPX_SCI_ANY_PHY_EXT_ADDR_MASK DPX_SCI_ANY_PHY_OUT_ADDR_MATCH DPX_SCI_ANY_PHY_INP_CFG_1 DPX_SCI_ANY_PHY_INP_CFG_2 DPX_SCI_ANY_PHY_ICA_ENBL_LSB DPX_SCI_ANY_PHY_ICA_ENBL_2 DPX_SCI_ANY_PHY_ICA_ENBL_3 DPX_SCI_ANY_PHY_ICA_ENBL_MSB DPX_SCI_ANY_PHY_OUT_CFG DPX_SCI_ANY_PHY_OUT_POLL_RNG DPX_ALL_PHY_REGS
Note: All configuration registers can be retrieved at once using DPX_ALL_PHY_REGS Outputs psSciAnyPhyRegs: Contents of the specified SCI-PHY/Any-PHY registers output by this function These contents are valid only if the function returns DPX_SUCCESS. Also, the only fields in this structure that are valid are those that have been requested using the input parameter, eSciAnyPhyRegId. Return Codes DPX_SUCCESS DPX_ERR_INVALID_DEVICE (invalid device handle) DPX_ERR_INVALID_STATE (invalid device state) DPX_ERR_INVALID_REG_ID (invalid register ID)
PROPRIETARY AND CONFIDENTIAL TO PMC-SIERRA, INC., AND FOR ITS CUSTOMERS' INTERNAL USE
69
PRELIMINARY DRIVER MANUAL PMC-990799 ISSUE 1
PM7350 S/UNI-DUPLEX DRIVER
S/UNI-DUPLEX DRIVER MANUAL
4.9.5 duplexSciAnyPhySetConfig: Configuring HSS-Links This function configures and modifies the contents of the specified HSS-link's configuration registers. It can set the value of individual configuration registers. Alternatively, it can set the entire configuration register set with one call. Valid States Side Effects Prototype DPX_INIT, DPX_ACTIVE None INT4 duplexSciAnyPhySetConfig(DUPLEX duplex, eDPX_SCI_ANY_PHY_REG eSciAnyPhyRegId, sDPX_SCI_ANY_PHY_REGS *psSciAnyPhyRegs) duplex: Pointer to DDB that contains device context information maintained by the driver. eSciAnyPhyRegId: Specifies the register containing the value to be set; can be one of: * * * * * * * * * * * * DPX_SCI_ANY_PHY_EXT_ADDR_MATCH DPX_SCI_ANY_PHY_EXT_ADDR_MASK DPX_SCI_ANY_PHY_OUT_ADDR_MATCH DPX_SCI_ANY_PHY_INP_CFG_1 DPX_SCI_ANY_PHY_INP_CFG_2 DPX_SCI_ANY_PHY_ICA_ENBL_LSB DPX_SCI_ANY_PHY_ICA_ENBL_2 DPX_SCI_ANY_PHY_ICA_ENBL_3 DPX_SCI_ANY_PHY_ICA_ENBL_MSB DPX_SCI_ANY_PHY_OUT_CFG DPX_SCI_ANY_PHY_OUT_POLL_RNG DPX_ALL_PHY_REGS
Inputs
Note: All configuration registers can be set at once using DPX_ALL_PHY_REGS. psSciAnyPhyRegs: Contents of the specified SCI-PHY/Any-PHY registers that this function will set. These contents are valid only if the function returns DPX_SUCCESS. Also, only those fields of this structure are valid that have been requested using the input parameter, eSciAnyPhyRegId.
PROPRIETARY AND CONFIDENTIAL TO PMC-SIERRA, INC., AND FOR ITS CUSTOMERS' INTERNAL USE
70
PRELIMINARY DRIVER MANUAL PMC-990799 ISSUE 1
PM7350 S/UNI-DUPLEX DRIVER
S/UNI-DUPLEX DRIVER MANUAL
Outputs Return Codes
None DPX_SUCCESS DPX_ERR_INVALID_DEVICE (invalid device handle) DPX_ERR_INVALID_STATE (invalid device state) DPX_ERR_INVALID_REG_ID (invalid register ID)
4.10
Clocked Serial-Data Interface Functions The clocked serial-data interface functions perform the following tasks: * * * Reads from transmit and receive serial-channel context bytes Writes to transmit and receive serial-channel context bytes Enables and disables automatic reset of the HCS error-count register
4.10.1 duplexRxSerChnlReadReg: Reading from Receive Serial-Channel Context Bytes This function indirectly reads a receive serial-channel context byte. Valid States Side Effects Prototype DPX_INIT, DPX_PRESENT None INT4 duplexRxSerChnlReadReg(DUPLEX duplex, UINT1 u1SerChnlId, eDPX_CLK_SER_REG eClkSerRegId, UINT1 *pu1RegVal)
PROPRIETARY AND CONFIDENTIAL TO PMC-SIERRA, INC., AND FOR ITS CUSTOMERS' INTERNAL USE
71
PRELIMINARY DRIVER MANUAL PMC-990799 ISSUE 1
PM7350 S/UNI-DUPLEX DRIVER
S/UNI-DUPLEX DRIVER MANUAL
Inputs
duplex: Pointer to DDB that contains device context information maintained by the driver u1SerChnlId: Serial channel identifier (0 through 15) eClkSerRegId: Specifies the register containing the value that the function will retrieve. It can be one of the following: * * * * * DPX_CLK_SER_RX_CHNL_CFG DPX_CLK_SER_RX_INT_ENBLS DPX_CLK_SER_RX_INT_STATUS DPX_CLK_SER_RX_HCS_ERR_CNT DPX_CLK_SER_LCD_CNT_THRESH
Outputs
pu1RegVal: Contents of the specified clocked-bit serial-interface registers output by this function. These contents are valid only if the function returns DPX_SUCCESS. DPX_SUCCESS DPX_ERR_INVALID_DEVICE (invalid device handle) DPX_ERR_INVALID_STATE (invalid device state) DPX_ERR_INVALID_CHNL_ID (invalid serial channel ID) DPX_ERR_INVALID_REG_ID (invalid register ID)
Return Codes
4.10.2 duplexRxSerChnlWriteReg: Writing to Receive Serial-Channel Context Bytes This function indirectly writes to a receive serial-channel context byte. Valid States Side Effects Prototype DPX_INIT, DPX_PRESENT None INT4 duplexRxSerChnlWriteReg(DUPLEX duplex, UINT1 u1SerChnlId, eDPX_CLK_SER_REG eClkSerRegId, UINT1 u1RegVal)
PROPRIETARY AND CONFIDENTIAL TO PMC-SIERRA, INC., AND FOR ITS CUSTOMERS' INTERNAL USE
72
PRELIMINARY DRIVER MANUAL PMC-990799 ISSUE 1
PM7350 S/UNI-DUPLEX DRIVER
S/UNI-DUPLEX DRIVER MANUAL
Inputs
duplex: Pointer to DDB that contains device context information maintained by the driver u1SerChnlId: Serial channel identifier (0 through 15) eClkSerRegId: Specifies the register containing the value that the function will retrieve. It can be one of the following: * * * DPX_CLK_SER_RX_CHNL_CFG DPX_CLK_SER_RX_INT_ENBLS DPX_CLK_SER_LCD_CNT_THRESH
u1RegVal: Contents of the specified clocked-bit serial-interface register that this function will set Return Codes DPX_SUCCESS DPX_ERR_INVALID_DEVICE (invalid device handle) DPX_ERR_INVALID_STATE (invalid device state) DPX_ERR_INVALID_CHNL_ID (invalid serial channel ID) DPX_ERR_INVALID_REG_ID (invalid register ID) 4.10.3 duplexRxSerChnlHCSCntResetEn: Enabling Auto Reset of HCS Error Registers This function enables or disables automatic reset of the HCS error-count register when an indirect read is initiated. Valid States Side Effects Prototype Inputs DPX_INIT, DPX_ACTIVE None INT4 duplexRxSerChnlHCSCntResetEn(DUPLEX duplex, UINT1 u1Enable) duplex: Pointer to DDB that contains device context information maintained by the driver u1Enable: If value is 0, the flag enables auto reset. If the value is not 0, the flag disables autoreset.
PROPRIETARY AND CONFIDENTIAL TO PMC-SIERRA, INC., AND FOR ITS CUSTOMERS' INTERNAL USE
73
PRELIMINARY DRIVER MANUAL PMC-990799 ISSUE 1
PM7350 S/UNI-DUPLEX DRIVER
S/UNI-DUPLEX DRIVER MANUAL
Return Codes
DPX_SUCCESS DPX_ERR_INVALID_DEVICE (invalid device handle) DPX_ERR_INVALID_STATE (invalid device state)
4.10.4 duplexTxSerChnlReadReg: Reading from Transmit Serial-Channel Context Bytes This function indirectly reads a transmit serial-channel context byte. Valid States Side Effects Prototype DPX_INIT, DPX_PRESENT None INT4 duplexTxSerChnlReadReg(DUPLEX duplex, UINT1 u1SerChnlId, eDPX_CLK_SER_REG eClkSerRegId, UINT1 *pu1RegVal) duplex: Pointer to DDB that contains device context information maintained by the driver u1SerChnlId: Serial channel identifier (0 through 15) eClkSerRegId: Specifies the register containing the value that this function will retrieve. Its value can be one of the following: * * Outputs DPX_CLK_SER_TX_DATA DPX_CLK_SER_TX_SER_FRM_BIT_THRESH
Inputs
pu1RegVal: Contents of the specified clocked-bit serial-interface register output by this function. These contents are valid only if the function returns DPX_SUCCESS
PROPRIETARY AND CONFIDENTIAL TO PMC-SIERRA, INC., AND FOR ITS CUSTOMERS' INTERNAL USE
74
PRELIMINARY DRIVER MANUAL PMC-990799 ISSUE 1
PM7350 S/UNI-DUPLEX DRIVER
S/UNI-DUPLEX DRIVER MANUAL
Return Codes
DPX_SUCCESS DPX_ERR_INVALID_DEVICE (invalid device handle) DPX_ERR_INVALID_STATE (invalid device state) DPX_ERR_INVALID_CHNL_ID (invalid serial channel ID) DPX_ERR_INVALID_REG_ID (invalid register ID)
4.10.5 duplexTxSerChnlWriteReg: Writing to Transmit Serial-Channel Context Bytes This function indirectly writes to a transmit serial-channel context byte. Valid States Side Effects Prototype DPX_INIT, DPX_PRESENT None INT4 duplexTxSerChnlWriteReg(DUPLEX duplex, UINT1 u1SerChnlId, eDPX_CLK_SER_REG eClkSerRegId, UINT1 u1RegVal) duplex: Pointer to DDB that contains device context information maintained by the driver u1SerChnlId: Serial channel identifier (0 through 15) eClkSerRegId: Specifies the register containing the value that this function will retrieve. It can be one of the following: * * DPX_CLK_SER_TX_DATA DPX_CLK_SER_TX_SER_FRM_BIT_THRESH
Inputs
u1RegVal: Contents of the specified clocked-bit serial-interface register that this function will set
PROPRIETARY AND CONFIDENTIAL TO PMC-SIERRA, INC., AND FOR ITS CUSTOMERS' INTERNAL USE
75
PRELIMINARY DRIVER MANUAL PMC-990799 ISSUE 1
PM7350 S/UNI-DUPLEX DRIVER
S/UNI-DUPLEX DRIVER MANUAL
Return Codes
DPX_SUCCESS DPX_ERR_INVALID_DEVICE (invalid device handle) DPX_ERR_INVALID_STATE (invalid device state) DPX_ERR_INVALID_CHNL_ID (invalid serial channel ID) DPX_ERR_INVALID_REG_ID (invalid register ID)
4.11
Statistics Collection This section describes the API functions used to collect statistics about the device's HSS links. Their tasks include: * * * * Accumulating the received-cell count and header-check sequence (HCS) cell-error count for a specified HSS link Accumulating the transmitted-cell count for a specified HSS link Reading all the cell counts (transmit and receive) for all the HSS links of the specified device Retrieving and resetting the statistical counts maintained by the driver
4.11.1 duplexGetHssLnkRxCounts: Accumulating Counts for Received Cells This function accumulates the counts for received cells and errored HCS cells for a specified HSS link (RXD1 or RXD2). It triggers an update of the receive HSS cell-counter registers and the receive-HSS HCS error-count register. It then reads the contents of these registers and returns the values read to the application. To maintain a steady count, without overflow, of received cells and HCS cell errors, the application should call this function at least every 30 seconds. Valid States Side Effects DPX_ACTIVE You should not use this function at the same time (in periodic polling fashion) as duplexGetAllHssLnkCounts because both functions trigger updates to the receive counters. INT4 duplexGetHssLnkRxCounts(DUPLEX duplex, UINT1 u1HssLnkId, UINT4 *pu4RxCells, UINT4 *pu4HcsErrs)
Prototype
PROPRIETARY AND CONFIDENTIAL TO PMC-SIERRA, INC., AND FOR ITS CUSTOMERS' INTERNAL USE
76
PRELIMINARY DRIVER MANUAL PMC-990799 ISSUE 1
PM7350 S/UNI-DUPLEX DRIVER
S/UNI-DUPLEX DRIVER MANUAL
Inputs
duplex: Pointer to DDB that contains device context information maintained by the driver u1HssLnkId: HSS link identifier. Valid identifiers are DPX_RXD1 and DPX_RXD2.
Outputs
pu4RxCells: Count of cells received pu4HcsErrs: Count of errored HCS-cells received
Return Codes
DPX_SUCCESS DPX_ERR_INVALID_DEVICE (invalid device handle) DPX_ERR_INVALID_STATE (invalid device state) DPX_ERR_INVALID_LNK_ID (invalid link ID)
4.11.2 duplexGetHssLnkTxCounts: Accumulating Counts for Transmitted Cells This function accumulates the counts for transmitted cells for a specified HSS link (TXD1 or TXD2). It triggers an update of the transmit HSS cell-counter registers. It then reads the contents of these registers and returns the values read to the application. To maintain a steady count, without overflow, of transmitted cells, the application should call this function at least every 30 seconds. Valid States Side Effects DPX_ACTIVE You should not use this function at the same time (in periodic polling fashion) as duplexGetAllHssLnkCounts because both functions trigger updates to the transmit counters. INT4 duplexGetHssLnkTxCounts(DUPLEX duplex, UINT4 *pu4TxCells) duplex: Pointer to DDB that contains device context information maintained by the driver pu4TxCells: Count of cells transmitted
Prototype Inputs
Outputs
PROPRIETARY AND CONFIDENTIAL TO PMC-SIERRA, INC., AND FOR ITS CUSTOMERS' INTERNAL USE
77
PRELIMINARY DRIVER MANUAL PMC-990799 ISSUE 1
PM7350 S/UNI-DUPLEX DRIVER
S/UNI-DUPLEX DRIVER MANUAL
Return Codes
DPX_SUCCESS DPX_ERR_INVALID_DEVICE (invalid device handle) DPX_ERR_INVALID_STATE (invalid device state)
4.11.3 duplexGetAllHssCounts: Accumulating Counts for All Cells This function reads all the cell counts (transmit and receive) for all the serial links of the specified S/UNI-DUPLEX device. This function triggers an update to the RXD1 and RXD2 receive and transmit counters by writing a dummy value to the load performance meters register. It then reads the counters of all the serial links and returns the contents to the calling function. To maintain a steady count of cells received, cells transmitted, and HCS errored cells on a per-link basis for all the serial links, and to avoid overflow, the application should call this function at least every 30 seconds. Valid States Side Effects DPX_ACTIVE You should not use this function at the same time (in periodic polling fashion) as duplexGetHssLnkRxCounts and duplexGetHssLnkTxCounts because both functions trigger updates to the same counters. INT4 duplexGetAllHssCounts(DUPLEX duplex, sDPX_HSS_CNTS *psHssCnts) duplex: Pointer to DDB that contains device context information maintained by the driver psHssCnts: Contains the RXD1 and RXD2 cells received, errored received cells, and transmitted cells DPX_SUCCESS DPX_ERR_INVALID_DEVICE (invalid device handle) DPX_ERR_INVALID_STATE (invalid device state)
Prototype Inputs
Outputs
Return Codes
PROPRIETARY AND CONFIDENTIAL TO PMC-SIERRA, INC., AND FOR ITS CUSTOMERS' INTERNAL USE
78
PRELIMINARY DRIVER MANUAL PMC-990799 ISSUE 1
PM7350 S/UNI-DUPLEX DRIVER
S/UNI-DUPLEX DRIVER MANUAL
4.11.4 duplexGetStatisticCounts: Retrieving Driver Statistical Counts This function retrieves the statistical counts maintained by the driver. It contains the counts for events and interrupts of the S/UNI-DUPLEX device since the last call to reset statistic counts. Valid States Side Effects Prototype Inputs All states except DPX_EMPTY None INT4 duplexGetStatisticCounts(DUPLEX duplex, sDPX_STAT_COUNTS *psStatCounts) duplex: Pointer to DDB that contains the count information maintained by the driver psStatCounts: Contains statistical counts of events and interrupts DPX_SUCCESS DPX_ERR_INVALID_DEVICE (invalid device handle) 4.11.5 duplexResetStatisticCounts: Resetting Driver Statistical Counts This function resets the statistical counts maintained by the driver. Valid States Side Effects Prototype Inputs All states except DPX_EMPTY None INT4 duplexResetStatisticCounts(DUPLEX duplex) duplex: Pointer to DDB that contains the count information maintained by the driver None DPX_SUCCESS DPX_ERR_INVALID_DEVICE (invalid device handle)
Outputs
Return Codes
Outputs Return Codes
PROPRIETARY AND CONFIDENTIAL TO PMC-SIERRA, INC., AND FOR ITS CUSTOMERS' INTERNAL USE
79
PRELIMINARY DRIVER MANUAL PMC-990799 ISSUE 1
PM7350 S/UNI-DUPLEX DRIVER
S/UNI-DUPLEX DRIVER MANUAL
4.12
Indication Callbacks The DPR uses indication callback functions to notify the application of events in the S/UNI-DUPLEX device and driver. You must implement these functions to work within the inter-task communication and scheduling capabilities of your RTOS. Typically, the callback functions will run in the context of the DPR, not in the context of the application. Therefore, these functions must be non-blocking. They should use RTOS-based inter-task notification to pass callback information safely from the DPR to the application task.
4.12.1 indDuplexNotify: Notifying the Application of Significant Events This indication function notifies the application about the occurrence of a significant event in the hardware or the driver software. The duplexDPR function calls this function. This function should be non-blocking. Typically, the indication function sends a message to another task with the event identifier and other context information. The task that receives this message can then process this information according to the system requirements. Prototype Inputs VOID indDuplexNotify(USR_CTXT usrCtxt, sDPX_IND_BUF *pIndBuf) usrCtxt: Context information (maintained by your system) for the device pIndBuf: Information regarding the indication. It consists of an event identifier that identifies the reported event. Uniquely supplemental information about the event. The application should use duplexReturnIndBuf to free the indication context structure. Outputs Return Codes None None
4.12.2 indDuplexRxBOC: Notifying the Application of Received BOC This indication function notifies the application about the reception of a valid BOC. The duplexDPR function calls this function. This function should be non-blocking. Prototype VOID indDuplexRxBOC(USR_CTXT usrCtxt, sDPX_IND_BUF *pIndBuf)
PROPRIETARY AND CONFIDENTIAL TO PMC-SIERRA, INC., AND FOR ITS CUSTOMERS' INTERNAL USE
80
PRELIMINARY DRIVER MANUAL PMC-990799 ISSUE 1
PM7350 S/UNI-DUPLEX DRIVER
S/UNI-DUPLEX DRIVER MANUAL
Inputs
usrCtxt: Context information (maintained by your system) for the device pIndBuf: Information regarding the indication. It consists of: * * u1HssLnkId: HSS link that received the BOC. u1BOC: BOC received. It can be one of the following: * * * * * * * 000000b (RDI) 000001b (loopback activate) 000010b (loopback deactivate) 000011b (remote reset activate) 000100b (remote reset deactivate) 010001b to 111110b (defined by you) 111111b (idle code)
The application should use duplexReturnIndBuf to free the indication context structure. Outputs Return Codes None None
4.12.3 indDuplexRxCell: Notifying the Application of Ready Extract-Cell-FIFOs This indication function notifies the application of the reception of cells in the microprocessor extract cell FIFOs. The duplexDPR function calls this function. This function should be non-blocking. Typically, the indication function sends a message to another task with the event identifier and other context information. The task that receives this message can then extract the received cells using duplexCheckExtractFifos and duplexExtractCell. Prototype Inputs VOID indDuplexRxCell(USR_CTXT usrCtxt, sDPX_IND_BUF *pIndBuf) usrCtxt: Context information (maintained by your system) for the device pIndBuf: Information regarding the indication. Currently, the driver does not use it, so the driver passes a null pointer for now. Outputs Return Codes None None
PROPRIETARY AND CONFIDENTIAL TO PMC-SIERRA, INC., AND FOR ITS CUSTOMERS' INTERNAL USE
81
PRELIMINARY DRIVER MANUAL PMC-990799 ISSUE 1
PM7350 S/UNI-DUPLEX DRIVER
S/UNI-DUPLEX DRIVER MANUAL
PROPRIETARY AND CONFIDENTIAL TO PMC-SIERRA, INC., AND FOR ITS CUSTOMERS' INTERNAL USE
82
PRELIMINARY DRIVER MANUAL PMC-990799 ISSUE 1
PM7350 S/UNI-DUPLEX DRIVER
S/UNI-DUPLEX DRIVER MANUAL
5
REAL-TIME-OS INTERFACE FUNCTIONS The driver's RTOS interface module provides functions and macros that let the driver use RTOS services. The S/UNI-DUPLEX driver requires the following RTOS services: * * * Memory: Allocate and deallocate Interrupts: Install and remove Preemption: Enable and disable
The driver may also require the following additional RTOS services depending on how you customize the code (for example, the ISR, the DPR, and so on). These services are: * * * Timers: Create, delete, start and abort Tasks: Spawn and delete Message queues: Create and destroy queues, send and receive messages
Figure 8 illustrates the external interfaces defined for the S/UNI-DUPLEX driver.
PROPRIETARY AND CONFIDENTIAL TO PMC-SIERRA, INC., AND FOR ITS CUSTOMERS' INTERNAL USE
83
PRELIMINARY DRIVER MANUAL PMC-990799 ISSUE 1
PM7350 S/UNI-DUPLEX DRIVER
S/UNI-DUPLEX DRIVER MANUAL
Figure 8: Real-Time OS Interface
Application
Function Calls
Indication Callbacks
Service Calls
S/UNI-DUPLEX Driver
RTOS
RTOS Interface
Hardware Interrupts Register Access
S/UNI-DUPLEX Device
5.1
Memory Allocation and Deallocation This section describes the RTOS interface functions used to allocate and deallocate memory.
5.1.1 sysDuplexMemAlloc: Allocating Memory This macro allocates a specified number of bytes. Prototype Inputs Outputs #define sysDuplexMemAlloc(nbytes) malloc(nbytes) nbytes: Number of bytes to be allocated None
PROPRIETARY AND CONFIDENTIAL TO PMC-SIERRA, INC., AND FOR ITS CUSTOMERS' INTERNAL USE
84
PRELIMINARY DRIVER MANUAL PMC-990799 ISSUE 1
PM7350 S/UNI-DUPLEX DRIVER
S/UNI-DUPLEX DRIVER MANUAL
Return Codes
Pointer to first byte of allocated memory NULL pointer (memory allocation failed)
5.1.2 sysDuplexMemFree: Deallocating Memory This macro deallocates memory allocated by sysDuplexMemAlloc. Prototype Inputs #define sysDuplexMemFree(pu1First) free(pu1First) pu1First: Pointer to first byte of the memory region being deallocated None None
Outputs Return Codes 5.2
Buffer Management This section describes the RTOS interface functions used to manage buffers for the DPR. Their tasks include getting a buffer for saving the context information for the indication callbacks, and returning the buffer after the application has received the context information.
5.2.1 duplexGetIndBuf: Getting DPR Buffers This function gets a buffer that saves the context information for the indication callbacks called by the DPR. Prototype Inputs Outputs Return Codes sDPX_IND_BUF *duplexGetIndBuf(VOID) None None Pointer to indication context buffer NULL pointer (buffer unavailable)
PROPRIETARY AND CONFIDENTIAL TO PMC-SIERRA, INC., AND FOR ITS CUSTOMERS' INTERNAL USE
85
PRELIMINARY DRIVER MANUAL PMC-990799 ISSUE 1
PM7350 S/UNI-DUPLEX DRIVER
S/UNI-DUPLEX DRIVER MANUAL
5.2.2 duplexReturnIndBuf: Returning DPR Buffers This function returns the indication context buffer after the DPR has received the context information. Prototype Inputs Outputs Return Codes 5.3 VOID duplexReturnIndBuf(sDPX_IND_BUF *pBuf) pBuf: Pointer to indication context structure None None
Timer Operations This section describes the RTOS interface function used to suspend a task for a specified period.
5.3.1 sysDuplexDelayFn: Delaying Functions This function suspends execution of the calling function's task for a specified number of milliseconds. Prototype Inputs Outputs Return Codes 5.4 VOID sysDuplexDelayFn(UINT4 u4Msecs) u4Msecs: Delay (in milliseconds) None None
Semaphore Operations This section describes the RTOS interface macros used to manage semaphores. Their tasks include: * * * Creating a new mutual-exclusion semaphore Deleting a specified semaphore Taking and giving semaphores
PROPRIETARY AND CONFIDENTIAL TO PMC-SIERRA, INC., AND FOR ITS CUSTOMERS' INTERNAL USE
86
PRELIMINARY DRIVER MANUAL PMC-990799 ISSUE 1
PM7350 S/UNI-DUPLEX DRIVER
S/UNI-DUPLEX DRIVER MANUAL
5.4.1 sysDuplexSemCreate: Creating Semaphores This macro creates a new mutual-exclusion semaphore. Prototype Inputs Outputs Return Codes #define sysDuplexSemCreate() semMCreate() None None semaphore ID
5.4.2 sysDuplexSemDelete: Deleting Semaphores This macro deletes a specified semaphore. Prototype Inputs Outputs Return Codes #define sysDuplexSemDelete(semId) semDelete(semId) semaphore ID None None
5.4.3 sysDuplexSemTake: Taking Semaphores This macro takes a semaphore. Prototype Inputs Outputs Return Codes #define sysDuplexSemTake(semId) semTake(semId) semaphore ID None None
5.4.4 sysDuplexSemGive: Giving Semaphores This macro gives a semaphore.
PROPRIETARY AND CONFIDENTIAL TO PMC-SIERRA, INC., AND FOR ITS CUSTOMERS' INTERNAL USE
87
PRELIMINARY DRIVER MANUAL PMC-990799 ISSUE 1
PM7350 S/UNI-DUPLEX DRIVER
S/UNI-DUPLEX DRIVER MANUAL
Prototype Inputs Outputs Return Codes
#define sysDuplexSemGive(semId) semGive(semId) semaphore ID None None
PROPRIETARY AND CONFIDENTIAL TO PMC-SIERRA, INC., AND FOR ITS CUSTOMERS' INTERNAL USE
88
PRELIMINARY DRIVER MANUAL PMC-990799 ISSUE 1
PM7350 S/UNI-DUPLEX DRIVER
S/UNI-DUPLEX DRIVER MANUAL
6
HARDWARE INTERFACE FUNCTIONS The S/UNI-DUPLEX hardware interface provides functions and macros that read from and write to S/UNI-DUPLEX device-registers. The hardware interface also provides a template for an ISR that the driver calls when the device raises a hardware interrupt. You must modify this function based on the interrupt configuration of your system. Figure 9 illustrates the external interfaces defined for the S/UNI-DUPLEX driver. Figure 9: Hardware Interface
Application
Function Calls
Indication Callbacks
Service Calls
S/UNI-DUPLEX Driver
RTOS
Hardware Interrupts
Register Access
Hardware Interface
S/UNI-DUPLEX Device
6.1
Device Register Access This section describes the hardware interface functions used to read from and write to S/UNI-DUPLEX device registers. Their tasks include reading and writing the contents of a specific address. It also includes getting the base address of the new device so that the driver can access the device register map to control it.
PROPRIETARY AND CONFIDENTIAL TO PMC-SIERRA, INC., AND FOR ITS CUSTOMERS' INTERNAL USE
89
PRELIMINARY DRIVER MANUAL PMC-990799 ISSUE 1
PM7350 S/UNI-DUPLEX DRIVER
S/UNI-DUPLEX DRIVER MANUAL
6.1.1 sysDuplexRawRead: Reading from Register Address Locations This low-level system-specific macro reads the contents of a specific register-address location. You should define this to reflect your system's addressing logic. Prototype Inputs Outputs #define sysDuplexRawRead(addr, val) addr: Address location to be read val: Value read
6.1.2 sysDuplexRawWrite: Writing to Register Address Locations This low-level system-specific macro writes the contents of a specific register-address location. You should define this macro to reflect your system's addressing logic. Prototype Inputs #define sysDuplexRawWrite(addr, val) addr: Address location to write val: Value to be written Outputs None
6.1.3 sysDuplexDeviceDetect: Getting Device Base Addresses This function uses user context information to detect new S/UNI-DUPLEX devices. The duplexAdd API function calls it. This function's implementation is system specific. Prototype Inputs INT4 sysDuplexDeviceDetect(DPX_USR_CTXT usrCtxt, VOID **ppSysInfo, UINT4 *pu4BaseAddr) usrCtxt: Context information (maintained by your system) for the device
PROPRIETARY AND CONFIDENTIAL TO PMC-SIERRA, INC., AND FOR ITS CUSTOMERS' INTERNAL USE
90
PRELIMINARY DRIVER MANUAL PMC-990799 ISSUE 1
PM7350 S/UNI-DUPLEX DRIVER
S/UNI-DUPLEX DRIVER MANUAL
Outputs
pu4BaseAddr: Base address of device ppSysInfo: Pointer to a system information buffer, which contains system specific information
Return Codes
DPX_SUCCESS DPX_DEVICE_NOT_DETECTED
6.2
Interrupt Servicing This section describes the hardware interface functions used to provide hardware interrupt servicing. They install and remove the interrupt handlers and DPRs for the S/UNI-DUPLEX devices. These functions depend on whether you implement the driver in interrupt mode or polling mode. In interrupt mode, their tasks include: * Installing and removing the system-dependent interrupt-handler function (sysDuplexIntHandler) and the DPR function (sysDuplexDPRTask), creating a communication channel between the two, and adding the device to a list of devices for which interrupts will be serviced Removing the specified device from the list of devices for which interrupt processing will be done Calling duplexISR for each device for which interrupt processing is enabled Retrieving interrupt status information saved for it by the sysDuplexIntHandler function, and calling the duplexDPR function for the appropriate device
* * *
In polling mode, these functions' tasks include: * * * Spawning and removing the sysDuplexDPRTask function Adding the device to a list of devices that need polling Polling the S/UNI-DUPLEX device for interrupt status information and processing the interrupt status
The S/UNI-DUPLEX driver provides a function called duplexISR that checks if there are any valid interrupt conditions present for a specified device. This function can be used by a system-specific interrupt-handler function to service interrupts raised by S/UNI-DUPLEX devices.
PROPRIETARY AND CONFIDENTIAL TO PMC-SIERRA, INC., AND FOR ITS CUSTOMERS' INTERNAL USE
91
PRELIMINARY DRIVER MANUAL PMC-990799 ISSUE 1
PM7350 S/UNI-DUPLEX DRIVER
S/UNI-DUPLEX DRIVER MANUAL
The low-level interrupt handler function that traps the hardware interrupt and calls duplexISR is system and RTOS dependent. Therefore, it is outside the scope of the driver. As a reference, this manual provides an example implementation of such an interrupt handler (see sysDuplexIntHandler) as well as installation and removal functions (see sysDuplexIntInstallHandler and sysDuplexIntRemoveHandler). You can customize these example implementations as per your specific requirements. 6.2.1 duplexISR: Registering Interrupt Statuses This function reads the top-level interrupt-status registers of the interrupting device. If there are any bits set in these registers, this function returns a value greater than zero. If there are no bits set, this function returns a zero. This function is invoked by the system-specific interrupt-handler function, sysDuplexIntHandler. Note: In polling mode, the driver does not use this function. Valid States Side Effects DPX_ACTIVE If the function returns with a non-zero value (meaning interrupt conditions have been detected), then all device interrupts are disabled. UINT4 duplexISR(DUPLEX duplex) duplex : Pointer to DDB that contains device context information maintained by the driver None = 0 (no valid interrupt conditions detected) > 0 (at least one valid interrupt condition detected) 6.2.2 duplexDPR: Processing Interrupts This function performs the following tasks: * * * Reads the device interrupt-status registers Clears the interrupt conditions Invokes user-defined callback functions that perform system-specific processing based on the interrupt conditions detected
Prototype Inputs
Outputs Return Codes
PROPRIETARY AND CONFIDENTIAL TO PMC-SIERRA, INC., AND FOR ITS CUSTOMERS' INTERNAL USE
92
PRELIMINARY DRIVER MANUAL PMC-990799 ISSUE 1
PM7350 S/UNI-DUPLEX DRIVER
S/UNI-DUPLEX DRIVER MANUAL
The system-specific DPR-task function, sysDuplexDPRTask, invokes this function. Valid States Side Effects Prototype Inputs DPX_ACTIVE Enables device interrupts after processing all the existing interrupt conditions VOID duplexDPR(DUPLEX duplex) duplex: Pointer to DDB that contains device context information maintained by the driver None None
Outputs Return Codes
6.2.3 sysDuplexIntInstallHandler: Installing Interrupt Service Functions In interrupt mode, this function installs sysDuplexIntHandler in the processor vector table, spawns the sysDuplexDPRTask function as a task, and creates a communication channel (for example, a message queue) between the two. In addition, it adds the S/UNI-DUPLEX device to a list of devices that need interrupt servicing. In polling mode, this function spawns the sysDuplexDPRTask function. This function periodically polls the device for interrupts and services the interrupts. It also adds the S/UNI-DUPLEX device to a list of devices that need polling services. Prototype Inputs Outputs Return Codes INT4 sysDuplexIntInstallHandler(DUPLEX duplex) duplex: Pointer to device context information None DPX_SUCCESS DPX_ERR_INT_ALREADY DPX_ERR_INT_INSTALL
PROPRIETARY AND CONFIDENTIAL TO PMC-SIERRA, INC., AND FOR ITS CUSTOMERS' INTERNAL USE
93
PRELIMINARY DRIVER MANUAL PMC-990799 ISSUE 1
PM7350 S/UNI-DUPLEX DRIVER
S/UNI-DUPLEX DRIVER MANUAL
6.2.4 sysDuplexIntRemoveHandler: Removing Interrupt Service Functions In interrupt mode, this function removes the specified device from the list of devices that need interrupt processing. If this is the last active device, the function deletes the sysDuplexDPRTask and associated message queue. It also removes the sysDuplexIntHandler function from the processor's interrupt-vector table. In polling mode, this function removes the specified device from the list of devices that need polling services. If this is the last active device, this function deletes sysDuplexDPRTask. Prototype Inputs Outputs Return Codes VOID sysDuplexIntRemoveHandler(DUPLEX duplex) duplex: Pointer to device context information None None
6.2.5 sysDuplexIntHandler: Calling duplexISR In interrupt mode, this function calls duplexISR for each device with interrupt processing enabled. The driver calls this function when one or more S/UNI-DUPLEX devices interrupt the microprocessor. If duplexISR detects at least one valid pending interrupt condition, then this function queues the interrupt context information for later processing by sysDuplexDPRTask. In polling mode, this function is not used. Prototype Inputs Outputs Return Codes sysDuplexIntHandler(INT4 Irq) Irq: IRQ number of interrupt None None
PROPRIETARY AND CONFIDENTIAL TO PMC-SIERRA, INC., AND FOR ITS CUSTOMERS' INTERNAL USE
94
PRELIMINARY DRIVER MANUAL PMC-990799 ISSUE 1
PM7350 S/UNI-DUPLEX DRIVER
S/UNI-DUPLEX DRIVER MANUAL
6.2.6 sysDuplexDPRTask: Calling duplexDPR In interrupt mode, the driver spawns this function as a separate task within the RTOS. It retrieves interrupt status information queued for it by the sysDuplexIntHandler function and calls the duplexDPR function for the appropriate device. In polling mode, the driver spawns this function as a separate task within the RTOS. It periodically calls the duplexDPR function for each active device. Prototype Inputs Outputs Return Codes VOID sysDuplexDPRTask(VOID) None None None
PROPRIETARY AND CONFIDENTIAL TO PMC-SIERRA, INC., AND FOR ITS CUSTOMERS' INTERNAL USE
95
PRELIMINARY DRIVER MANUAL PMC-990799 ISSUE 1
PM7350 S/UNI-DUPLEX DRIVER
S/UNI-DUPLEX DRIVER MANUAL
PROPRIETARY AND CONFIDENTIAL TO PMC-SIERRA, INC., AND FOR ITS CUSTOMERS' INTERNAL USE
96
PRELIMINARY DRIVER MANUAL PMC-990799 ISSUE 1
PM7350 S/UNI-DUPLEX DRIVER
S/UNI-DUPLEX DRIVER MANUAL
7
PORTING DRIVERS This section outlines how to port the S/UNI-DUPLEX device driver to your hardware and OS platform. Note: Because each platform and application is unique, this manual can only offer guidelines for porting the S/UNI-DUPLEX driver.
7.1
Driver Source Files The C source files listed in Figure 7-1 contain the code for the S/UNI-DUPLEX driver. You may need to modify the code or develop additional code. The code is in the form of constants, macros, and functions. For the ease of porting, the code is grouped into source files (src) and include files (inc). The src files contain the functions and the inc files contain the constants and macros. Figure 10: Driver Source Files
dpxdrv src dpx_api.c (contains all API functions) dpx.c (contains driver internal functions) dpx_hw.c (contains hardware interface functions) dpx_rtos.c (contains RTOS interface functions) dpx_test.c (contains sample driver callback functions and test code)
inc
dpx_api.h (contains data-structure definitions and prototypes) dpx.h (contains device register-address and bit-mask definitions) dpx_hw.h (contains device-interface macro and constant definitions) dpx_rtos.h (contains RTOS-interface macro and constant definitions) dpx_err.h (contains driver error codes) dpx_test.h (contains data structure definitions and protot ypes of test code)
Makefile
7.2
Driver Porting Procedures The following steps summarize how to port the S/UNI-DUPLEX driver to your platform. The following sections describe these steps in more detail.
PROPRIETARY AND CONFIDENTIAL TO PMC-SIERRA, INC., AND FOR ITS CUSTOMERS' INTERNAL USE
97
PRELIMINARY DRIVER MANUAL PMC-990799 ISSUE 1
PM7350 S/UNI-DUPLEX DRIVER
S/UNI-DUPLEX DRIVER MANUAL
Note: Because each platform and application is unique, this manual can only offer guidelines for porting the S/UNI-DUPLEX driver. To port the S/UNI-DUPLEX driver to your platform: 1. Port the driver's OS extensions (page 98): * * * Data types OS specific services Utilities and interrupt services that use OS specific services
2. Port the driver to your hardware platform (page 100): * * * Port the device detection function. Port low-level device read-and-write macros. Define hardware system-configuration constants.
3. Port the driver's application-specific elements (page 102): * * Define the task-related constants. Code the callback functions.
4. Build the driver (page 103). 7.2.1 Porting Driver OS Extensions The OS extensions encapsulate all OS specific services and data types used by the driver. The dpx_rtos.h file contains data types and compiler-specific data-type definitions. It also contains macros for OS specific services used by the OS extensions. These OS extensions include: * * * * * Task management Message queues Timers Events Semaphores
PROPRIETARY AND CONFIDENTIAL TO PMC-SIERRA, INC., AND FOR ITS CUSTOMERS' INTERNAL USE
98
PRELIMINARY DRIVER MANUAL PMC-990799 ISSUE 1
PM7350 S/UNI-DUPLEX DRIVER
S/UNI-DUPLEX DRIVER MANUAL
*
Memory Management
In addition, you may need to modify functions that use OS specific services, such as utility and interrupt-event handling functions. The dpx_rtos.c file contains the utility and interrupt-event handler functions that use OS specific services. To port the driver's OS extensions: 1. Modify the data types in dpx_rtos.h. The number after the type identifies the data-type size. For example, UINT4 defines a 4-byte (32-bit) unsigned integer. Substitute the compiler types that yield the desired types as defined in this file. 2. Modify the OS specific services in dpx_rtos.h. Redefine the following macros to the corresponding system calls that your target system supports: Service Type Memory Macro Name sysDuplexMemAlloc sysDuplexMemFree sysDuplexMemCopy Description Allocates the memory block Frees the memory block Copies the memory block from src to dest Creates the mutually exclusive semaphore Frees the mutually exclusive semaphore relinquishes the mutually exclusive semaphore Gets the mutually exclusive semaphore
Semaphore
sysDuplexSemCreate
sysDuplexSemDelete
sysDuplexSemGive
sysDuplexSemTake
3. Modify the utilities and interrupt services that use OS specific services in the dpx_rtos.c. The dpx_rtos.c file contains the utility and interrupt-event handler functions that use OS specific services. Refer to the function headers in this file for a detailed description of each of the functions listed below:
PROPRIETARY AND CONFIDENTIAL TO PMC-SIERRA, INC., AND FOR ITS CUSTOMERS' INTERNAL USE
99
PRELIMINARY DRIVER MANUAL PMC-990799 ISSUE 1
PM7350 S/UNI-DUPLEX DRIVER
S/UNI-DUPLEX DRIVER MANUAL
Service Type Memory
Function Name sysDuplexMemSet
Description Sets each character in the memory buffer Gets a block of memory for the indication buffer Frees the indication buffer Sets the task execution delay in milliseconds Installs the interrupt handler for the OS Removes the interrupt handler from the OS Interrupt handler for the S/UNI-DUPLEX device Deferred interrupt-processing routine (DPR)
duplexGetIndBuf
duplexReturnIndBuf
Timer
sysDuplexDelayFn
Interrupt
sysDuplexIntInstallHandler
sysDuplexIntRemoveHandler
sysDuplexIntHandler
sysDuplexDPRTask
7.2.2 Porting Drivers to Hardware Platforms This section describes how to modify the S/UNI-DUPLEX driver for your hardware platform. Before you build the driver, ensure that you port the driver's OS extensions (page 98).
PROPRIETARY AND CONFIDENTIAL TO PMC-SIERRA, INC., AND FOR ITS CUSTOMERS' INTERNAL USE
100
PRELIMINARY DRIVER MANUAL PMC-990799 ISSUE 1
PM7350 S/UNI-DUPLEX DRIVER
S/UNI-DUPLEX DRIVER MANUAL
To port the driver to your hardware platform: 1. Modify the device detection function in the dpx_hw.c file. The function sysDuplexDeviceDetect is implemented for a PCI platform. Modify it to reflect your specific hardware interface. Its purpose is to detect a S/UNI-DUPLEX device based on a user-context input parameter. It returns two output parameters: * * The base address of the S/UNI-DUPLEX device A pointer to the system-specific configuration information
2. Modify the low-level device read/write macros in the dpx_hw.h file. You may need to modify the raw read/write access macros (sysDuplexRawRead and sysDuplexRawWrite) to reflect your system's addressing logic. 3. Define the hardware system-configuration constants in the dpx_hw.h file. Modify the following constants to reflect your system's hardware configuration: #define DPX_MEM_ADDR_RANGE Description The assigned address memory range for each S/UNI-DUPLEX device. Your system's memory map determines it. The maximum number of S/UNI-DUPLEX cards allowed in the system Note: The DSLAM architecture allows up to 16 S/UNI-DUPLEX cards. DPX_ADAPTER_MAX_DEVS The maximum number of S/UNI-DUPLEX devices on each card Default
0x800
DPX_ADAPTER_MAX_UNITS
7
1
PROPRIETARY AND CONFIDENTIAL TO PMC-SIERRA, INC., AND FOR ITS CUSTOMERS' INTERNAL USE
101
PRELIMINARY DRIVER MANUAL PMC-990799 ISSUE 1
PM7350 S/UNI-DUPLEX DRIVER
S/UNI-DUPLEX DRIVER MANUAL
7.2.3 Porting Driver Application-Specific Elements Application specific elements are configuration constants used by the API for developing an application. This section describes how to modify the application specific elements in the S/UNI-DUPLEX driver. Before you port the driver's application-specific elements, ensure that you: 1. Port the driver's OS extensions (page 98). 2. Port the driver to your hardware platform (page 100). To port the driver's application-specific elements: 1. Define the following driver task-related constants for your OS-specific services in file dpx_rtos.h: #define DPX_DPR_TASK_PRIORITY DPX_DPR_TASK_STACK_SZ DPX_POLLING_DELAY Description Deferred Task (DPR) task priority DPR task stack size, in bytes Constant used in polling task mode, this constant defines the interval time in millisecond between each polling action Delay time in millisecond. When clearing the DPR loop active flag in the DPR task, this delay is used to gracefully shutdown the DPR task before deleting it. Default
85 4096 10
DPX_TASK_SHUTDOWN_DELAY
10
DPX_MAX_DPR_MSGS
The queue message depth of the 10 queue used for pass interrupt context between the ISR task and DPR task Maximum indication buffer size in 53 bytes The maximum number of S/UNI-DUPLEX devices in the system (from 1 to 128)
DPX_MAX_IND_BUFSZ
DPX_MAX_NUM_DEVS
7
PROPRIETARY AND CONFIDENTIAL TO PMC-SIERRA, INC., AND FOR ITS CUSTOMERS' INTERNAL USE
102
PRELIMINARY DRIVER MANUAL PMC-990799 ISSUE 1
PM7350 S/UNI-DUPLEX DRIVER
S/UNI-DUPLEX DRIVER MANUAL
2. Code the callback functions according to your application. There are four sample callback functions in the dpx_test.c file. You can use these callback functions or you can customize them before using the driver. The driver will call these callback functions when an event occurs on the device. These functions must conform to the following prototypes: * * * * VOID indDuplexNotify(DPX_USR_CTXT usrCtxt, sDPX_IND_BUF *psIndCtxt) VOID indDuplexRxBOC(DPX_USR_CTXT usrCtxt, sDPX_IND_BUF *psIndCtxt) VOID indDuplexCell(DPX_USR_CTXT usrCtxt, sDPX_IND_BUF *psIndCtxt) UINT1 pCellTypeFn(UINT1 *pu1Hdr, UINT4 *pu4Crc32Prev)
7.2.4 Building Drivers This section describes how to build the S/UNI-DUPLEX driver. Before you build the driver, ensure that you: 1. Port the driver's OS extensions (page 98). 2. Port the driver to your hardware platform (page 100). 3. Port the driver's application-specific elements (page 102). To build the driver: 1. Modify the makefile's compile-switch flag DPX_CSW_INTERRUPT_MODE. Set it to one for interrupt mode or zero for polling mode. 2. Set the makefile's compile-switch flag CSW_PV_FLAG to zero. This disables the test code specific to product verification. 3. Ensure that the directory variable names in the makefile reflect your actual driver and directory names. 4. Compile the source files and build the S/UNI-DUPLEX API driver library using your make utility.
PROPRIETARY AND CONFIDENTIAL TO PMC-SIERRA, INC., AND FOR ITS CUSTOMERS' INTERNAL USE
103
PRELIMINARY DRIVER MANUAL PMC-990799 ISSUE 1
PM7350 S/UNI-DUPLEX DRIVER
S/UNI-DUPLEX DRIVER MANUAL
5. Link the S/UNI-DUPLEX API driver library to your application code.
PROPRIETARY AND CONFIDENTIAL TO PMC-SIERRA, INC., AND FOR ITS CUSTOMERS' INTERNAL USE
104
PRELIMINARY DRIVER MANUAL PMC-990799 ISSUE 1
PM7350 S/UNI-DUPLEX DRIVER
S/UNI-DUPLEX DRIVER MANUAL
APPENDIX: CODING CONVENTIONS This section describes the coding and naming conventions used in the implementation of the driver software. This section also describes the variable types. Definition of Variable Types The following table describes the variable types used by the S/UNI-DUPLEX driver. Table 16: Definition of Variable Types Type Description unsigned integer, 1 byte unsigned integer, 2 bytes unsigned integer, 4 bytes signed integer, 1 byte signed integer, 2 bytes signed integer, 4 bytes void void *, pointer to user maintained device context void *, pointer to driver maintained device context
UINT1 UINT2 UINT4 INT1 INT2 INT4 VOID DPX_USR_CTXT DUPLEX
Naming Conventions The names for variables, functions, and macros (but not constants) include prefixes that indicate their type. Variable, function, and macro names that contain multiple words have the first letter of each word capitalized. Variables The following table describes the prefixes used for the driver's variables.
PROPRIETARY AND CONFIDENTIAL TO PMC-SIERRA, INC., AND FOR ITS CUSTOMERS' INTERNAL USE
105
PRELIMINARY DRIVER MANUAL PMC-990799 ISSUE 1
PM7350 S/UNI-DUPLEX DRIVER
S/UNI-DUPLEX DRIVER MANUAL
Table 17: Variable Naming Conventions Variable Type Prefix u1 u2 u4 i1 i2 i4 s e p Example u1Flag u2Code u4Val i1Flag i2Code i4Val sCellHdr eHssRegId pu1Flag pi4Val psCellHdr peHssRegId Pointer to a Pointer pp ppu1Flag ppi4Val ppsCellHdr ppeHssRegId
UINT1 UINT2 UINT4 INT1 INT2 INT4
Structure Variable Enumerated Type Pointers
Functions and Macros The following table describes the prefixes used for the driver's functions and macros.
PROPRIETARY AND CONFIDENTIAL TO PMC-SIERRA, INC., AND FOR ITS CUSTOMERS' INTERNAL USE
106
PRELIMINARY DRIVER MANUAL PMC-990799 ISSUE 1
PM7350 S/UNI-DUPLEX DRIVER
S/UNI-DUPLEX DRIVER MANUAL
Table 18: Function and Macro Naming Conventions Function Type API Functions Indication Functions System-Specific Functions and Macros Prefix duplex indDuplex sysDuplex Example Name duplexAdd indDuplexRxCell sysDuplexIntHandler
Definable Constants You can define some constants using the "#define" command. These constants have names that are composed of all uppercase letters with underscores separating multiple words. An example is DPX_NUM_HSS_LNKS.
PROPRIETARY AND CONFIDENTIAL TO PMC-SIERRA, INC., AND FOR ITS CUSTOMERS' INTERNAL USE
107
PRELIMINARY DRIVER MANUAL PMC-990799 ISSUE 1
PM7350 S/UNI-DUPLEX DRIVER
S/UNI-DUPLEX DRIVER MANUAL
PROPRIETARY AND CONFIDENTIAL TO PMC-SIERRA, INC., AND FOR ITS CUSTOMERS' INTERNAL USE
108
PRELIMINARY DRIVER MANUAL PMC-990799 ISSUE 1
PM7350 S/UNI-DUPLEX DRIVER
S/UNI-DUPLEX DRIVER MANUAL
ACRONYMS API: Application programming interface DDB: Device data block BOC: Bit oriented code DPR: Deferred interrupt-processing routine GDD: Global driver database HCS: Header check sequence HSS link: High-speed serial link ISR: Interrupt service routine RTOS: Real-time operating system
PROPRIETARY AND CONFIDENTIAL TO PMC-SIERRA, INC., AND FOR ITS CUSTOMERS' INTERNAL USE
109
PRELIMINARY DRIVER MANUAL PMC-990799 ISSUE 1
PM7350 S/UNI-DUPLEX DRIVER
S/UNI-DUPLEX DRIVER MANUAL
PROPRIETARY AND CONFIDENTIAL TO PMC-SIERRA, INC., AND FOR ITS CUSTOMERS' INTERNAL USE
110
PRELIMINARY DRIVER MANUAL PMC-990799 ISSUE 1
PM7350 S/UNI-DUPLEX DRIVER
S/UNI-DUPLEX DRIVER MANUAL
INDEX
A Accessing Registers, 89 Accumulating Counts, 76, 77, 78 Acronyms, 109 Activating Devices, 52 Adding Devices, 45 addr, 90 Addresses, 90 Allocating Memory, 84 API Module, 17 Application Interface Functions, 43 Architecture, 16, 17 Auto Reset, 73 B-C Base Addresses, 90 BOC, 15, 43, 65, 66, 67 Buffers, 85, 86 Building Drivers, 103 Callback Functions, 64 Calling duplexDPR, 25, 95 Calling duplexISR, 24, 91, 94 Cell Data Structures, 29 Cell Extraction, 22, 23, 59 Cell Insertion, 59, 60 Cell-Control Data Structure, 29 Cell-Header Data Structure, 29 CELLXFERRE, 37 Clocked Serial-Data Interface Functions, 71 Clocks, 55 Coding Conventions, 105 Collecting Statistics, 16, 76 Configuration Information, 57, 58, 68 Configuring HSS Links, 70 Contents of Extract-FIFO-Ready Registers, 63 Count Structures, 38 Count_Clock_Lock_Fail, 39 Count_Extract_Cell_CRC_Error, 39 Count_Extract_Cells, 41 Count_Interrupts, 41 Count_Invalid_SOC_Sequence, 39 Count_Micro_Insert_Fifo_Full, 39 Count_Micro_Insert_Fifo_Ready, 39 Count_Phy_Input_Cell_Xfered, 39 Count_Phy_Input_Parity, 39 Count_Phy_Output_Error, 39 Count_Rx_BOCs, 41 Count_Rx_Lc_Fifo_Overflow, 39 Count_RxHss_Active_Bit, 40 Count_RxHss_Count_Overflow, 41 Count_RxHss_Count_Updated, 41 Count_RxHss_Extract_Fifo, 40 Count_RxHss_HCS_Error, 41 Count_RxHss_In_Delin, 40 Count_RxHss_In_Sync, 41 Count_RxHss_Loss_Of_Signal, 40 Count_RxHss_No_Active_Bit, 40 Count_RxHss_Out_Of_Delin, 40 Count_RxHss_Out_Of_Sync, 41 Count_RxHss_Signal_Detected, 40 Count_RxSerChnl_Fifo_Overflow, 40 Count_RxSerChnl_HCS_Error, 40 Count_RxSerChnl_In_Delin, 39 Count_RxSerChnl_in_Sync, 40 Count_RxSerChnl_Out_Of_Delin, 39 Count_RxSerChnl_Out_Of_Sync, 40 Count_Tx_Hss_Count_Overflow, 39 Count_Tx_Hss_Count_Updated, 39 Count_Tx_Lc_Fifo_Overflow, 39 Counts, 38, 39 Counts for All Cells, 78 Counts for Received Cells, 76 Counts for Transmitted Cells, 77 Creating Semaphores, 87 CSW_PV_FLAG, 103 D Data Structures, 29 DDBs, 33, 34 Deactivating Devices, 52 Deallocating Memory, 85 Deferred-Processing Routine Module, 19 Delaying Functions, 86 Deleting Devices, 45, 47 Deleting Semaphores, 87 dest, 99 Device Activation, 52 Device Addition, 45 Device Data Block, 18, 34 Device Deactivation, 52 Device Deletion, 45
PROPRIETARY AND CONFIDENTIAL TO PMC-SIERRA, INC., AND FOR ITS CUSTOMERS' INTERNAL USE
111
PRELIMINARY DRIVER MANUAL PMC-990799 ISSUE 1
PM7350 S/UNI-DUPLEX DRIVER
S/UNI-DUPLEX DRIVER MANUAL
Device Diagnostics, 15, 53 Device Initialization, 15, 21, 22, 49 Device Interface Functions, 89 Device Re-initialization, 21, 22 Device Reset, 45 Device Shutdown, 21, 22 Device-Configuration Data Structures, 30 Device-Context Data Structures, 33 Diagnosing Devices, 15, 53 Diagnostic or Line Loopback, 54 Disabling Diagnostic or Line Loopback, 54 DPR, 19 DPR Buffers, 85, 86 DPX_ADAPTER_MAX_DEVS, 101 DPX_ADAPTER_MAX_UNITS, 101 DPX_ALL_HSS_REGS, 58, 59 DPX_ALL_PHY_REGS, 69, 70 DPX_CB_NOTIFY, 51 DPX_CB_RX_BOC, 51 DPX_CB_RX_CELL, 51 DPX_CELLTYPE_FN, 31, 36 DPX_CLK_BIT_SER, 35 DPX_CLK_SER_LCD_CNT_THRESH, 72, 73 DPX_CLK_SER_RX_CHNL_CFG, 72, 73 DPX_CLK_SER_RX_HCS_ERR_CNT, 72 DPX_CLK_SER_RX_INT_ENBLS, 72, 73 DPX_CLK_SER_RX_INT_STATUS, 72 DPX_CLK_SER_TX_DATA, 74, 75 DPX_CLK_SER_TX_SER_FRM_BIT_THRESH, 74, 75 DPX_CSW_INTERRUPT_MODE, 103 DPX_DEVICE_NOT_DETECTED, 91 DPX_DIAG_LPBK, 54 DPX_DPR_TASK_PRIORITY, 102 DPX_DPR_TASK_STACK_SZ, 102 DPX_EMPTY, 35, 46, 47, 54, 55, 79 DPX_EOM_FN, 65 DPX_ERR_CB_FN_NOT_INSTALLED, 63 DPX_ERR_CELL_RX_CRC, 63 DPX_ERR_CELL_TX_BUSY, 61 DPX_ERR_DEV_ID_TYPE, 46 DPX_ERR_DEV_NOT_DETECTED, 46 DPX_ERR_EXCEED_REG_RANGE, 48, 49 DPX_ERR_INDIRECT_CHANNEL_BUSY, 50 DPX_ERR_INT_ALREADY, 93 DPX_ERR_INT_INSTALL, 93 DPX_ERR_INVALID_BOC, 66, 67 DPX_ERR_INVALID_CB_TYPE, 51, 52 DPX_ERR_INVALID_CHNL_ID, 72, 73, 75, 76
DPX_ERR_INVALID_FLAG, 55 DPX_ERR_INVALID_HSS_ID, 55 DPX_ERR_INVALID_INIT_VECTOR, 50 DPX_ERR_INVALID_LNK_ID, 63, 66, 67, 68, 77 DPX_ERR_INVALID_LPBK_TYPE, 55 DPX_ERR_MEM_ALLOC, 45, 46 DPX_ERR_MODULE_ALREADY_INIT, 45 DPX_FAILURE, 54 DPX_IND_CB_FN, 31, 35, 36, 50 DPX_LINE_LPBK, 54 DPX_LPBK_RESET, 54 DPX_LPBK_SET, 54 DPX_MAX_DPR_MSGS, 102 DPX_MAX_IND_BUFSZ, 102 DPX_MAX_NUM_DEVS, 34, 38, 102 DPX_MEM_ADDR_RANGE, 101 DPX_NUM_HSS_LNKS, 107 DPX_POLLING_DELAY, 102 DPX_RX_HSS_CELL_FILTER_CFG_RXD, 58, 59 DPX_RX_HSS_CFG_RXD, 58, 59 DPX_RX_HSS_LNK_SELECT_AUTO, 56, 57 DPX_RX_HSS_LNK_SELECT_RXD, 56, 57 DPX_RXD, 54, 62, 66, 67, 68, 77 DPX_SCI_ANY_PHY_EXT_ADDR_MASK, 69, 70 DPX_SCI_ANY_PHY_EXT_ADDR_MATCH, 69, 70 DPX_SCI_ANY_PHY_ICA_ENBL_, 69, 70 DPX_SCI_ANY_PHY_ICA_ENBL_LSB, 69, 70 DPX_SCI_ANY_PHY_ICA_ENBL_MSB, 69, 70 DPX_SCI_ANY_PHY_INP_CFG_, 69, 70 DPX_SCI_ANY_PHY_OUT_ADDR_MATCH, 69, 70 DPX_SCI_ANY_PHY_OUT_CFG, 69, 70 DPX_SCI_ANY_PHY_OUT_POLL_RNG, 69, 70 DPX_SCI_ANY_SLAVE, 35 DPX_SCI_MASTER, 35 DPX_SEM_ID, 36 DPX_TASK_SHUTDOWN_DELAY, 102 DPX_TX_HSS_CFG, 58, 59 DPX_USR_CTXT, 34, 46, 90, 103, 105 Driver Data Structures, 29 Driver Functions and Features, 15 Driver Hardware-Interface Module, 18 Driver Initialization, 44 Driver Library Module, 18 Driver Shutdown, 44, 45 Driver Software States, 19, 20
PROPRIETARY AND CONFIDENTIAL TO PMC-SIERRA, INC., AND FOR ITS CUSTOMERS' INTERNAL USE
112
PRELIMINARY DRIVER MANUAL PMC-990799 ISSUE 1
PM7350 S/UNI-DUPLEX DRIVER
S/UNI-DUPLEX DRIVER MANUAL
Driver Source Files, 97 DSLAM, 101 duplexActivate, 52 duplexAdd, 45, 46, 90, 107 duplexCheckExtractFifos, 63, 81 duplexDeactivate, 52, 53 duplexDelete, 25, 43, 47, 48 duplexDPR, 19, 23, 25, 26, 43, 49, 50, 51, 80, 81, 91, 92, 93, 95 duplexEnableRxCellInd, 64 duplexExtractCell, 61, 62, 64, 81 duplexGetAllHssCounts, 78 duplexGetAllHssLnkCounts, 76, 77 duplexGetClockStatus, 55 duplexGetHssLnkRxCounts, 76, 78 duplexGetHssLnkTxCounts, 77, 78 duplexGetIndBuf, 85, 100 duplexGetStatisticCounts, 79 duplexHssActiveLnkGetCfg, 56 duplexHssActiveLnkSetCfg, 57 duplexHssGetConfig, 57 duplexHssSetConfig, 58, 59 duplexInit, 49, 50 duplexInsertCell, 60 duplexInstallCellTypeFn, 64, 65 duplexInstallIndFn, 50 duplexISR, 19, 23, 24, 25, 26, 91, 92, 94 duplexLoopback, 54 duplexModuleInit, 44 duplexModuleShutdown, 45 duplexRead, 48 duplexRegisterTest, 53 duplexRemoteReset, 47 duplexRemoveIndFn, 51 duplexReset, 46, 47 duplexResetStatisticCounts, 79 duplexReturnIndBuf, 80, 81, 86, 100 duplexRxBOC, 66 duplexRxSerChnlHCSCntResetEn, 73 duplexRxSerChnlReadReg, 71 duplexRxSerChnlWriteReg, 72 duplexSciAnyPhyGetConfig, 68 duplexSciAnyPhySetConfig, 70 duplexSetAutoRDITx, 67 duplexTxBOC, 65 duplexTxSerChnlReadReg, 74 duplexTxSerChnlWriteReg, 75 duplexWrite, 49
E eCbType, 50, 51 eClkSerRegId, 71, 72, 73, 74, 75 eDevMode, 35 eDevState, 35 eDPX_CB_TYPE, 50, 51 eDPX_CLK_SER_REG, 71, 72, 74, 75 eDPX_HSS_REG, 57, 59 eDPX_MODE, 35 eDPX_SCI_ANY_PHY_REG, 68, 70 eDPX_STATE, 35 eHSS_LNK_SEL, 56, 57 eHssRegId, 57, 58, 59, 106 eLnkSel, 57 Enabling Auto Reset of HCS Error Registers, 73 Enabling Diagnostic or Line Loopback, 54 Enabling Received Cell Indicators, 64 Error Registers, 73 errored, 16, 76, 77, 78 eSciAnyPhyRegId, 68, 69, 70 Events, 80 Extract-FIFO-Ready Register, 63 Extracting Cells, 22, 23, 61 F-G FIFOs, 16, 31, 36, 63, 81 Files, 97, 103 Flow Processing, 20 FOVRE, 37 Functions and Features, 15 GDD, 33, 44, 45, 109 Getting Contents of Extract-FIFO-Ready Registers, 63 Getting Device Base Addresses, 90 Getting DPR Buffers, 85 Getting HSS-Link Configuration Information, 57 Getting HSS-Link Selection Method Information, 56 Getting SCI-PHY/Any-PHY Configuration Information, 68 Giving Semaphores, 87 Global Driver-Database Structure, 33 H-K Hardware Interface, 18, 89 HCS, 38, 71, 73, 76, 78, 109 HCSPASS, 33 HSS Counts, 38 HSS Link Cell Extraction, 59
PROPRIETARY AND CONFIDENTIAL TO PMC-SIERRA, INC., AND FOR ITS CUSTOMERS' INTERNAL USE
113
PRELIMINARY DRIVER MANUAL PMC-990799 ISSUE 1
PM7350 S/UNI-DUPLEX DRIVER
S/UNI-DUPLEX DRIVER MANUAL
HSS Link Cell Insertion, 59 HSS Link Configuration, 15, 56, 57, 58 HSS Link Selection, 56 HSS Links, 57, 60, 61, 70 IDLEI, 66 IFCLK, 55 inc, 13, 97 indDuplex, 107 indDuplexCell, 103 indDuplexNotify, 80, 103 indDuplexRxBOC, 66, 80, 103 indDuplexRxCell, 81, 107 Indication Callbacks, 16, 50, 51, 80 indNotify, 31, 35 indRxBOC, 31, 36 indRxCell, 31, 36 Init, 20 Initialization, 44 Initialization Data Structure, 30 Initializing Devices, 15, 21, 22, 49 Initializing Driver Modules, 44 Inserting Cells into HSS Links, 60 Installing Callback Functions, 64 Installing Indication Callback Functions, 50 Installing Interrupt Service Functions, 93 Interrupt Data Structures, 36 Interrupt Processing, 92 Interrupt Service Functions, 93, 94 Interrupt Servicing, 16, 23, 91 Interrupt Statuses, 92 Interrupt-Context Data Structure, 37 Interrupt-Enable Data Structure, 36 Interrupt-Service Routine Module, 19 IRQ, 34, 94 ISR, 16, 23, 36, 91 ISR Data Structure, 36 ISR Module, 19 L-M Library Module, 18 Line Loopback, 54 lockId, 36 loopback, 15, 53, 54, 55, 65, 66, 67, 81 LSB, 32 Make Files, 103 malloc, 84 Memory, 84, 85 Modifying HSS-Link Configuration Information, 58
Monitoring Device Clocks, 55 MSB, 32 N-Q nbytes, 84 Notifying Applications, 80, 81 OFCLK, 55 Other Devices, 47 pBuf, 86 pCbFn, 50, 51 pCellTypeFn, 31, 36, 65, 103 PCI, 34, 101 pDdb, 34 pDuplex, 46 peHssRegId, 106 peLnkSel, 56 pIndBuf, 80, 81 Polling Servicing, 26 Porting Application-Specific Elements, 102 Porting Drivers, 97, 100 Porting Drivers to Hardware Platforms, 100 Porting OS Extensions, 98 Porting Procedures, 97 Porting Quick Start, 13 ppeHssRegId, 106 ppsCellHdr, 106 ppSysInfo, 90, 91 Processing Flows, 20 Processing Interrupts, 92 psCellHdr, 60, 61, 62, 106 psCtrl, 60, 61, 62 psHssCnts, 78 psHssRegs, 57, 58, 59 psIndCtxt, 103 psSciAnyPhyRegs, 68, 69, 70 psStatCounts, 79 pSysInfo, 34 R RDI, 65, 66, 67, 68, 81 RDIDIS, 65 Reading from Receive Serial-Channel Context Bytes, 71 Reading from Received BOC, 66 Reading from Register Address Locations, 90 Reading from Registers, 48 Reading from Transmit Serial-Channel Context Bytes, 74 Ready Extract-Cell-FIFOs, 81
PROPRIETARY AND CONFIDENTIAL TO PMC-SIERRA, INC., AND FOR ITS CUSTOMERS' INTERNAL USE
114
PRELIMINARY DRIVER MANUAL PMC-990799 ISSUE 1
PM7350 S/UNI-DUPLEX DRIVER
S/UNI-DUPLEX DRIVER MANUAL
Receive Serial-Channel Context Bytes, 71, 72 Received BOC, 66, 80 Received Cell Indicator, 64 Received Cells, 76 REFCLK, 55 Register Access, 53, 89 Register Address Locations, 90 Register Data Structure, 31 Registering Interrupt Statuses, 92 Registers, 48, 49, 73 Re-initializing Devices, 21, 22 Remote Defect Indications, 67 Removing Indication Callback Functions, 51 Removing Interrupt Service Functions, 94 Resetting Devices, 45, 46 Resetting Other Devices, 47 Resetting Statistical Counts, 79 Retrieving Statistical Counts, 79 Returning DPR Buffers, 86 ROOLE, 37 ROOLV, 37 RSTOB, 47 RTOS, 25 RTOS Interface, 18, 83 S sCellHdr, 106 SCI-PHY/Any-PHY Configuration, 68 sClkSerRegs, 32 sDPX_CELL_CTRL, 30, 60, 62 sDPX_CELL_HDR, 29, 60, 62 sDPX_CLK_SER_REGS, 32, 33 sDPX_DDB, 34 sDPX_GDD, 34 sDPX_HSS_CNTS, 38, 78 sDPX_HSS_REGS, 32, 57, 59 sDPX_IND_BUF, 80, 81, 85, 86, 103 sDPX_INIT_VECT, 31, 35, 50 sDPX_INIT_VECTOR, 31, 35 sDPX_INT_CTXT, 38 sDPX_INT_ENBLS, 32, 35, 37 sDPX_REGS, 31 sDPX_SCI_ANY_PHY_REGS, 32, 68, 70 sDPX_STAT_COUNTS, 36, 39, 79 Selection Methods, 56 Semaphores, 86, 87 semDelete, 87 semGive, 88 semId, 87, 88
semMCreate, 87 semTake, 87 Setting Active HSS Links, 57 sHssRegs, 32 Shutdown, 44 Shutting Down Devices, 21, 22 Shutting Down Drivers, 45 Significant Events, 80 sInitVector, 35, 50 sIntEnbls, 35 sIntEnRegs, 32 Software States, 19, 20 Source Files, 97 src, 13, 97, 99 sRegInfo, 31 sSciAnyPhyRegs, 32 sStatCounts, 36 States, 19, 20 Statistical Counts, 38, 39, 79 Statistics Collection, 16, 76 sysDuplex, 26, 87, 99, 107 sysDuplexDelayFn, 86, 100 sysDuplexDeviceDetect, 90, 101 sysDuplexDPR, 23 sysDuplexDPRTask, 25, 26, 27, 91, 93, 94, 95, 100 sysDuplexIntHandler, 24, 25, 26, 91, 92, 93, 94, 95, 100, 107 sysDuplexIntInstallHandler, 25, 26, 92, 93, 100 sysDuplexIntRemoveHandler, 92, 94, 100 sysDuplexISR, 23 sysDuplexMemAlloc, 84, 85, 99 sysDuplexMemCopy, 99 sysDuplexMemFree, 85, 99 sysDuplexMemSet, 100 sysDuplexRawRead, 48, 90, 101 sysDuplexRawWrite, 49, 90, 101 sysDuplexSemCreate, 87, 99 sysDuplexSemDelete, 87, 99 sysDuplexSemGive, 87, 88, 99 sysDuplexSemTake, 87, 99 T-Z Taking Semaphores, 87 Timer Operations, 86 Transmit Serial-Channel Context Bytes, 74, 75 Transmitted Cells, 77 Transmitting BOC, 65 Transmitting Remote-Defect Indications, 67
PROPRIETARY AND CONFIDENTIAL TO PMC-SIERRA, INC., AND FOR ITS CUSTOMERS' INTERNAL USE
115
PRELIMINARY DRIVER MANUAL PMC-990799 ISSUE 1
PM7350 S/UNI-DUPLEX DRIVER
S/UNI-DUPLEX DRIVER MANUAL
UDF, 61 USR_CTXT, 80, 81 usrCtxt, 34, 46, 80, 81, 90, 103 val, 90 Verifying Register Access, 53
Writing to Receive Serial-Channel Context Bytes, 72 Writing to Registers, 48, 49, 90 Writing to Transmit Serial-Channel Context Bytes, 75
PROPRIETARY AND CONFIDENTIAL TO PMC-SIERRA, INC., AND FOR ITS CUSTOMERS' INTERNAL USE
116
PRELIMINARY DRIVER MANUAL PMC-990799 ISSUE 1
PM7350 S/UNI-DUPLEX DRIVER
S/UNI-DUPLEX DRIVER MANUAL
PROPRIETARY AND CONFIDENTIAL TO PMC-SIERRA, INC., AND FOR ITS CUSTOMERS' INTERNAL USE
117
PRELIMINARY DRIVER MANUAL PMC-990799 ISSUE 1
PM7350 S/UNI-DUPLEX DRIVER
S/UNI-DUPLEX DRIVER MANUAL
CONTACTING PMC-SIERRA, INC. PMC-Sierra, Inc. 105-8555 Baxter Place Burnaby, BC Canada V5A 4V7 Tel: (604) 415-6000 Fax: (604) 415-6200 Document Information: document@pmc-sierra.com Corporate Information: info@pmc-sierra.com Application Information: apps@pmc-sierra.com Web Site: http://www.pmc-sierra.com
None of the information contained in this document constitutes an express or implied warranty by PMC-Sierra, Inc. as to the sufficiency, fitness or suitability for a particular purpose of any such information or the fitness, or suitability for a particular purpose, merchantability, performance, compatibility with other parts or systems, of any of the products of PMC-Sierra, Inc., or any portion thereof, referred to in this document. PMC-Sierra, Inc. expressly disclaims all representations and warranties of any kind regarding the contents or use of the information, including, but not limited to, express and implied warranties of accuracy, completeness, merchantability, fitness for a particular use, or non-infringement. In no event will PMC-Sierra, Inc. be liable for any direct, indirect, special, incidental or consequential damages, including, but not limited to, lost profits, lost business or lost data resulting from any use of or reliance upon the information, whether or not PMC-Sierra, Inc. has been advised of the possibility of such damage. (c) 1999 PMC-Sierra, Inc. PMC-990799 (P1), ref PMC-981033 (P2) Issue date: July 1999
PROPRIETARY AND CONFIDENTIAL TO PMC-SIERRA, INC., AND FOR ITS CUSTOMERS' INTERNAL USE
118

▲Up To Search▲

Price & Availability of 1990799

	To Download 1990799 Datasheet File
If you can't view the Datasheet, Please click here to try to view without PDF Reader .